diff --git a/knowledge/repos/jiuwenswarm/components/a2ui/_index.md b/knowledge/repos/jiuwenswarm/components/a2ui/_index.md
index b0bffc62..05e7f56e 100644
--- a/knowledge/repos/jiuwenswarm/components/a2ui/_index.md
+++ b/knowledge/repos/jiuwenswarm/components/a2ui/_index.md
@@ -14,3 +14,4 @@ sources: []
 - [channels-web](channels-web/_index.md)
 - [server-runtime](server-runtime/_index.md)
 - [A2UI 生成式界面：实现深读](feature-depth-a2ui.md)
+- [a2ui owner — A2UI 生成式界面（后端集成与 Web 前端渲染）](knowledge-a2ui.md)
diff --git a/knowledge/repos/jiuwenswarm/components/a2ui/feature-a2ui.md b/knowledge/repos/jiuwenswarm/components/a2ui/feature-a2ui.md
index 232f3774..0a136e08 100644
--- a/knowledge/repos/jiuwenswarm/components/a2ui/feature-a2ui.md
+++ b/knowledge/repos/jiuwenswarm/components/a2ui/feature-a2ui.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/A2UI.md
 feature: "a2ui"
 entry_points: ["jiuwenswarm/server/runtime/a2ui/runtime/finalizer.py"]
-source_globs: ["jiuwenswarm/server/runtime/a2ui/runtime/finalizer.py", "jiuwenswarm/server/runtime/a2ui/*"]
+source_globs: ["jiuwenswarm/server/runtime/a2ui/runtime/finalizer.py", "jiuwenswarm/server/runtime/a2ui/*", "jiuwenswarm/channels/web/frontend/src/features/a2ui/actionBridge.ts", "jiuwenswarm/server/runtime/a2ui/prompt_instructions.py", "jiuwenswarm/server/runtime/a2ui/protocol.py", "jiuwenswarm/server/control/a2ui_config.py", "jiuwenswarm/channels/web/frontend/src/features/a2ui/a2uiContent.ts", "jiuwenswarm/channels/web/frontend/src/features/a2ui/fieldBinding.ts", "jiuwenswarm/channels/web/frontend/src/features/a2ui/formDefaults.ts", "jiuwenswarm/channels/web/frontend/src/features/a2ui/A2UIErrorBoundary.tsx", "jiuwenswarm/channels/web/frontend/src/features/a2ui/A2UIMessageContent.tsx", "jiuwenswarm/channels/web/frontend/src/features/a2ui/CheckBoxWithDefaults.tsx", "jiuwenswarm/channels/web/frontend/src/features/a2ui/DateTimeInputWithDefaults.tsx", "jiuwenswarm/channels/web/frontend/src/features/a2ui/MultipleChoiceWithDefaults.tsx", "jiuwenswarm/channels/web/frontend/src/features/a2ui/SliderWithDefaults.tsx", "jiuwenswarm/channels/web/frontend/src/features/a2ui/TextFieldWithDefaults.tsx", "jiuwenswarm/channels/web/frontend/src/features/a2ui/TextWithDefaults.tsx", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ChatPanel.css", "jiuwenswarm/agents/harness/common/rails/response_prompt_rail.py", "jiuwenswarm/server/runtime/a2ui/protocols/__init__.py", "jiuwenswarm/channels/web/frontend/src/features/a2ui/rendererRegistry.tsx", "jiuwenswarm/server/runtime/a2ui/parser.py", "jiuwenswarm/server/runtime/agent_adapter/interface.py", "jiuwenswarm/server/runtime/a2ui/__init__.py", "jiuwenswarm/server/runtime/a2ui/config.py", "jiuwenswarm/server/runtime/a2ui/integration.py"]
 ---
 
 # A2UI 生成式界面 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/a2ui/knowledge-a2ui.md b/knowledge/repos/jiuwenswarm/components/a2ui/knowledge-a2ui.md
new file mode 100644
index 00000000..04a82dcc
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/a2ui/knowledge-a2ui.md
@@ -0,0 +1,61 @@
+---
+title: "a2ui owner — A2UI 生成式界面（后端集成与 Web 前端渲染）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/server/runtime/a2ui/integration.py:L120-L140, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/A2UI-IM-channel-analysis.md:L100-L122, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/a2ui/actionBridge.ts:L36-L99, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/a2ui/a2uiContent.ts:L169-L211, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/A2UI.md:L72-L87, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/A2UI-web-only-pr-record.md:L19-L35, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/a2ui/A2UIMessageContent.tsx:L124-L155, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/a2ui/actionBridge.ts:L125-L199, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/server/runtime/a2ui/integration.py:L65-L87, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/server/runtime/a2ui/parser.py:L92-L118, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/A2UI.md:L37-L55, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/server/runtime/a2ui/integration.py:L36-L45, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/a2ui/featureConfig.ts:L34-L43, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/server/runtime/a2ui/integration.py:L146-L155, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/a2ui/rendererRegistry.tsx:L22-L59, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/a2ui/MultipleChoiceWithDefaults.tsx:L91-L110, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/a2ui/MultipleChoiceWithDefaults.tsx:L150-L169, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/a2ui/MultipleChoiceWithDefaults.tsx:L254-L287, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/a2ui/A2UIMessageContent.tsx:L60-L96, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/a2ui/A2UIMessageContent.tsx:L157-L205, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/a2ui/actionBridge.ts:L101-L123, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/server/runtime/a2ui/config.py:L1-L31]
+---
+
+# a2ui owner — A2UI 生成式界面（后端集成与 Web 前端渲染）
+
+<!-- kb:knowledge owner=a2ui facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**Web-only 边界与对模型输出缺陷的防御性容错**
+
+Inference / 设计推断（非作者历史意图）：
+
+设计取舍（文档有明确记录）：A2UI 完整闭环依赖可控的浏览器 runtime（React/DOM、surface 状态、client_event 回传），因此 channel 策略集中在 `is_a2ui_channel`，当前仅 `web` 为真；非 Web 渠道直接 bypass，包括不做文本 fallback（`apply_non_web_text_fallback_to_payload` 现为透传的兼容 hook），换取 IM 渠道不感知 A2UI、普通聊天流程不受影响。推断（代码注释佐证但非作者完整陈述）：前端大量容错是针对模型输出质量的花费——`cleanActionContext` 修复模型生成的 `[object Object]` context 键，`extractTextFromMalformedA2UI` 从坏 JSON 中抢救可读文本；这些启发式提高可用性但可能丢失或改写原始语义。
+
+Sources / 来源：[jiuwenswarm/server/runtime/a2ui/integration.py:L120–L140](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/server/runtime/a2ui/integration.py#L120-L140), [docs/zh/A2UI-IM-channel-analysis.md:L100–L122](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/docs/zh/A2UI-IM-channel-analysis.md#L100-L122), [jiuwenswarm/channels/web/frontend/src/features/a2ui/actionBridge.ts:L36–L99](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/a2ui/actionBridge.ts#L36-L99), [jiuwenswarm/channels/web/frontend/src/features/a2ui/a2uiContent.ts:L169–L211](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/a2ui/a2uiContent.ts#L169-L211)
+
+<!-- kb:knowledge owner=a2ui facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**既有验证入口**
+
+文档列出测试位置：`tests/unit_tests/a2ui/`、`tests/system_tests/test_a2ui_system_flow.py` 和前端脚本 `channels/web/frontend/scripts/test-a2ui-action-defaults.mjs`，并给出 pytest/npm build/ node 脚本的验证命令；Web-only PR 记录称 `test_integration_bridge.py`、`test_web_only_prompt_rail.py`、`test_feature_config.py` 覆盖 channel 策略、非 Web bypass 等行为（记录为 18 passed，是否当前仍通过未在本证据中复验）。前端各组件带稳定 `data-testid`（如 `a2ui-message-content`、`a2ui-multiplechoice`、`a2ui-textfield-input`），且 `A2UIMessageContent` 在 DEV 模式下用 requestAnimationFrame 检测横向溢出容器，可支撑 UI 级断言与调试。
+
+Sources / 来源：[docs/zh/A2UI.md:L72–L87](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/docs/zh/A2UI.md#L72-L87), [docs/zh/A2UI-web-only-pr-record.md:L19–L35](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/docs/zh/A2UI-web-only-pr-record.md#L19-L35), [jiuwenswarm/channels/web/frontend/src/features/a2ui/A2UIMessageContent.tsx:L124–L155](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/a2ui/A2UIMessageContent.tsx#L124-L155)
+
+<!-- kb:knowledge owner=a2ui facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**动作分发与事件转模型的入口契约**
+
+`dispatchA2UIAction(message)` 是前端交互出口：`open_form` 和 `close_modal` 被列为 frontend-only 动作直接跳过（注释说明是为了避免 chat.send 取消仍在渲染 A2UI surface 的流）；没有注册 handler 时记录开发警告并返回，重复的 in-flight 动作按 surfaceId+componentId+name 去重。后端入口 `build_user_prompt_if_a2ui_event(content, channel, language)` 仅当 channel 为 web、A2UI 开启且 content 是 `type == "a2ui.client_event"` 的 dict 时委托 `build_a2ui_client_event_prompt`，否则返回 None 让普通 prompt 流程继续。后端解析入口 `parse_a2ui_response` 先尝试整体 JSONL/JSON，再用 SDK 的 tagged 解析，返回 text/a2ui part 列表。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/src/features/a2ui/actionBridge.ts:L125–L199](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/a2ui/actionBridge.ts#L125-L199), [jiuwenswarm/server/runtime/a2ui/integration.py:L65–L87](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/server/runtime/a2ui/integration.py#L65-L87), [jiuwenswarm/server/runtime/a2ui/parser.py:L92–L118](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/server/runtime/a2ui/parser.py#L92-L118)
+
+<!-- kb:knowledge owner=a2ui facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**配置键、默认值与前后端布尔归一化差异**
+
+文档给出 `config.yaml` 默认 `a2ui.enabled: false`（另有 protocol_version "0.8"、stream_validation_enabled、non_web_fallback_enabled），可通过 Web 配置页开关、`config.yaml` 或 `JIUWENSWARM_A2UI_ENABLED` 控制；代码中 `get_default_a2ui_config_payload` 也以 `a2ui_enabled: "false"` 作为兜底。注意前后端布尔归一化并不等价：后端 `_to_bool` 只把 true/1/yes/on 视为真，前端 `normalizeA2UIEnabled` 把除 0/false/no/off 之外的一切（含缺失值）视为真；且 `validate_a2ui_config_update` 只校验并返回映射到 config.yaml 键的更新（`a2ui_enabled` → `enabled`），本身不写配置。
+
+Sources / 来源：[docs/zh/A2UI.md:L37–L55](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/docs/zh/A2UI.md#L37-L55), [jiuwenswarm/server/runtime/a2ui/integration.py:L36–L45](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/server/runtime/a2ui/integration.py#L36-L45), [jiuwenswarm/channels/web/frontend/src/features/a2ui/featureConfig.ts:L34–L43](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/a2ui/featureConfig.ts#L34-L43), [jiuwenswarm/server/runtime/a2ui/integration.py:L146–L155](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/server/runtime/a2ui/integration.py#L146-L155)
+
+<!-- kb:knowledge owner=a2ui facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**前端组件覆盖与组件变体行为**
+
+前端通过 `ComponentRegistry` 用 `*WithDefaults` 组件覆盖 Text、CheckBox、DateTimeInput、MultipleChoice、Slider、TextField 六种组件：覆盖在模块加载时提前注册一次，并在渲染器首次渲染时检查 `TextField` 是否仍是本组件、被库的惰性初始化覆盖时才重新应用。MultipleChoice 支持三种呈现——`type === 'chips'` 渲染为可选中的按钮 chips，多选（variant/type 为 chips/checkbox 或 maxAllowedSelections > 1）渲染为复选框列表，否则渲染为单选 `<select>` 下拉；过滤搜索框（filterable 为 true 或选项 ≥10 时显示）只出现在 chips 和复选框两种变体中，单选下拉不渲染搜索。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/src/features/a2ui/rendererRegistry.tsx:L22–L59](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/a2ui/rendererRegistry.tsx#L22-L59), [jiuwenswarm/channels/web/frontend/src/features/a2ui/MultipleChoiceWithDefaults.tsx:L91–L110](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/a2ui/MultipleChoiceWithDefaults.tsx#L91-L110), [jiuwenswarm/channels/web/frontend/src/features/a2ui/MultipleChoiceWithDefaults.tsx:L150–L169](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/a2ui/MultipleChoiceWithDefaults.tsx#L150-L169), [jiuwenswarm/channels/web/frontend/src/features/a2ui/MultipleChoiceWithDefaults.tsx:L254–L287](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/a2ui/MultipleChoiceWithDefaults.tsx#L254-L287)
+
+<!-- kb:knowledge owner=a2ui facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**A2UI 前端架构：解析、渲染与事件分发职责**
+
+Web 前端 A2UI 逻辑集中在 `channels/web/frontend/src/features/a2ui/`：`A2UIMessageContent` 解析 assistant message 中的 `<a2ui-json>` 块（`parseA2UIContent`），按协议版本从 `rendererRegistry` 取 renderer，将每个 surface 包在 `A2UIErrorBoundary` 内渲染，并把消息命名空间化后交给 `processMessages`。用户交互走 `dispatchA2UIAction`：它把消息直接传给已注册的 handler（不在此处包装协议信封），并做 frontend-only 动作短路、in-flight 去重与 context 清洗；包装为 `a2ui.client_event` 信封是独立的 `buildA2UIClientEventContent` 职责。后端 Runtime 侧 `server/runtime/a2ui/config.py` 只做薄转发：字典/env 解析留在 Control，避免 Front 配置查询导入 Runtime。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/src/features/a2ui/A2UIMessageContent.tsx:L60–L96](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/a2ui/A2UIMessageContent.tsx#L60-L96), [jiuwenswarm/channels/web/frontend/src/features/a2ui/A2UIMessageContent.tsx:L157–L205](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/a2ui/A2UIMessageContent.tsx#L157-L205), [jiuwenswarm/channels/web/frontend/src/features/a2ui/actionBridge.ts:L101–L123](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/a2ui/actionBridge.ts#L101-L123), [jiuwenswarm/channels/web/frontend/src/features/a2ui/actionBridge.ts:L125–L199](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/a2ui/actionBridge.ts#L125-L199), [jiuwenswarm/server/runtime/a2ui/config.py:L1–L31](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/server/runtime/a2ui/config.py#L1-L31)
+
diff --git a/knowledge/repos/jiuwenswarm/components/agent-runtime/_index.md b/knowledge/repos/jiuwenswarm/components/agent-runtime/_index.md
index 0462c180..d657ab4e 100644
--- a/knowledge/repos/jiuwenswarm/components/agent-runtime/_index.md
+++ b/knowledge/repos/jiuwenswarm/components/agent-runtime/_index.md
@@ -25,12 +25,11 @@ sources: []
 ## 代码快速入口（Direct）
 <!-- kb-init:quick-map -->
 
-触发词：runtime、AgentRuntime、session create/switch/fork、session.delete、plan mode、model catalog、permission snapshot、MCP reference、push handler、process CLI、agent definition、运行时、session lane、execution registry、work scheduler、deliver_control、cancel_execution、close_session、QUIESCING、control input、心跳链。PR 描述或改动命中下表一行时，先读该行的规则，再读页面其余部分。
+触发词：runtime、AgentRuntime、session create/switch/fork、session.delete、plan mode、model catalog、permission snapshot、MCP reference、push handler、process CLI、agent definition、运行时。PR 描述或改动命中下表一行时，先读该行的规则，再读页面其余部分。
 
 | PR 描述在做什么 | 精确规则 | 第一批 live 源码 |
 |---|---|---|
 | runtime、AgentRuntime、session create/switch/fork、session.delete、plan mode、model… | 入口 | `jiuwenswarm/runtime/agent_definition.py`、`jiuwenswarm/runtime/context.py`、`jiuwenswarm/runtime/events.py` |
-| session 执行协调、lane 排队、deliver_control、cancel_execution、close_session | Runtime Session 协调器（见目录内容） | `jiuwenswarm/runtime/session/coordinator.py`、`jiuwenswarm/runtime/session/execution_registry.py`、`jiuwenswarm/runtime/session/work_scheduler.py` |
 
 ## 验证入口
 
@@ -46,3 +45,6 @@ sources: []
 - [项目、会话与历史管理 功能知识](feature-projects-sessions.md)
 - [agent-runtime 源码接口与集成边界 01](source-contracts-01.md)
 - [项目、会话与历史管理：实现深读](feature-depth-projects-sessions.md)
+- [共享 Agent 运行时（jiuwenswarm/runtime/service.py AgentRuntime）](knowledge.md)
+- [声明式 root Agent 定义执行（invoke_agent/stream_agent）](feature-runtime-agent-definition-execution.md)
+- [会话输入通道（steer/follow_up）与执行绑定 — 知识页](feature-session-input-steering.md)
diff --git a/knowledge/repos/jiuwenswarm/components/agent-runtime/feature-projects-sessions.md b/knowledge/repos/jiuwenswarm/components/agent-runtime/feature-projects-sessions.md
index 7bc61061..fb21e684 100644
--- a/knowledge/repos/jiuwenswarm/components/agent-runtime/feature-projects-sessions.md
+++ b/knowledge/repos/jiuwenswarm/components/agent-runtime/feature-projects-sessions.md
@@ -11,7 +11,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/项目与会话管理.md
 feature: "projects-sessions"
 entry_points: ["jiuwenswarm/runtime/session_catalog.py", "jiuwenswarm/runtime/session_lifecycle.py"]
-source_globs: ["jiuwenswarm/runtime/session_catalog.py", "jiuwenswarm/runtime/session_lifecycle.py", "jiuwenswarm/runtime/session*.py"]
+source_globs: ["jiuwenswarm/runtime/session_catalog.py", "jiuwenswarm/runtime/session_lifecycle.py", "jiuwenswarm/runtime/session*.py", "jiuwenswarm/server/utils/diff_service.py", "jiuwenswarm/server/runtime/session/session_archive.py", "jiuwenswarm/channels/web/frontend/src/features/workspace/archivedTaskGrouping.ts", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/archivedTasks/useArchivedTaskLists.ts", "jiuwenswarm/common/cleanup.py", "jiuwenswarm/channels/browser/frontend/src/background/SessionManager.ts", "jiuwenswarm/channels/browser/frontend/src/sidepanel/index.ts", "jiuwenswarm/channels/browser/frontend/src/sidepanel/sidepanel.html", "jiuwenswarm/server/agent_ws_server.py", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/InputArea.tsx", "jiuwenswarm/server/runtime/agent_adapter/interface.py", "jiuwenswarm/channels/web/frontend/src/multi-session/state/createConversationSession.ts", "jiuwenswarm/channels/web/frontend/src/multi-session/sidebar/ConversationSidebar.css", "jiuwenswarm/channels/web/frontend/src/multi-session/sidebar/ConversationSidebar.tsx", "jiuwenswarm/server/runtime/agent_adapter/session_message_input.py", "jiuwenswarm/server/control/history_service.py", "jiuwenswarm/server/control/health_service.py", "jiuwenswarm/server/control/methods.py", "jiuwenswarm/server/control/responses.py", "jiuwenswarm/server/control/project_service.py", "jiuwenswarm/server/control/repositories/project_repository.py", "jiuwenswarm/server/control/repositories/session_repository.py", "jiuwenswarm/server/control/session_service.py", "jiuwenswarm/channels/web/frontend/src/features/code-mode/gitClient.ts", "jiuwenswarm/gateway/app_gateway.py", "jiuwenswarm/common/utils.py", "jiuwenswarm/common/git_safe_directory.py", "jiuwenswarm/server/runtime/session/session_history.py", "jiuwenswarm/channels/web/frontend/src/components/AgentPanel/FileViewer.tsx", "jiuwenswarm/channels/web/frontend/src/features/historyRestore.ts", "jiuwenswarm/server/runtime/session/history_io.py", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/MessageList.tsx", "jiuwenswarm/server/front/router.py", "jiuwenswarm/server/wire_truncate.py", "jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts", "jiuwenswarm/gateway/im_pipeline/im_session_input.py", "jiuwenswarm/server/runtime/session/session_metadata.py", "jiuwenswarm/agents/harness/common/session_ops_service.py", "jiuwenswarm/channels/web/frontend/src/multi-session/state/newConversationLifecycle.ts", "jiuwenswarm/channels/web/frontend/src/multi-session/state/newConversationPreviousSession.ts", "jiuwenswarm/channels/web/frontend/src/multi-session/state/newConversationProject.ts", "jiuwenswarm/server/runtime/offline_session_cleanup.py", "jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py", "jiuwenswarm/server/runtime/agent_adapter/interface_deep.py", "jiuwenswarm/channels/process_cli/app.py", "jiuwenswarm/channels/web/frontend/src/features/workspace/projectDirectoryPicker.ts", "jiuwenswarm/server/runtime/gateway_adapter/project_adapter.py", "jiuwenswarm/server/runtime/session/project_queries.py", "jiuwenswarm/channels/web/frontend/src/features/workspace/projectRegistryClient.ts", "jiuwenswarm/channels/web/frontend/src/features/workspace/projectTypes.ts", "jiuwenswarm/server/control/store/project_queries.py", "jiuwenswarm/server/runtime/session/project_store.py", "jiuwenswarm/common/projectless_workspace.py", "jiuwenswarm/runtime/session_provisioner.py", "jiuwenswarm/runtime/service.py", "jiuwenswarm/runtime/request.py", "jiuwenswarm/common/runtime_workspace.py", "jiuwenswarm/server/runtime/agent_adapter/sensitive_answers.py", "jiuwenswarm/channels/web/frontend/src/features/workspace/archivedTaskClient.ts", "jiuwenswarm/runtime/session/coordinator.py", "jiuwenswarm/runtime/session_delete.py", "jiuwenswarm/runtime/session/model.py", "jiuwenswarm/runtime/session/execution_registry.py", "jiuwenswarm/server/runtime/session/git_diff_status.py", "jiuwenswarm/server/runtime/gateway_adapter/session_adapter.py", "jiuwenswarm/channels/web/frontend/src/components/SessionsPanel/index.tsx", "jiuwenswarm/server/runtime/session/session_info.py", "jiuwenswarm/server/runtime/session/lifecycle.py", "jiuwenswarm/gateway/routing/session_map.py", "jiuwenswarm/server/runtime/session/model_selection_store.py", "jiuwenswarm/server/runtime/session/session_rename.py", "jiuwenswarm/server/runtime/agent_manager.py", "jiuwenswarm/channels/web/frontend/src/multi-session/sidebar/ProjectArchiveDialog.tsx", "jiuwenswarm/channels/web/frontend/src/multi-session/sidebar/projectArchiveModel.ts", "jiuwenswarm/channels/web/frontend/src/multi-session/sidebar/useSidebarMenu.tsx", "jiuwenswarm/channels/web/frontend/src/multi-session/sidebar/ProjectCreateMenu.tsx", "jiuwenswarm/channels/web/frontend/src/multi-session/sidebar/projectCreateErrors.ts", "jiuwenswarm/channels/web/frontend/src/multi-session/sidebar/SidebarActionMenu.tsx", "jiuwenswarm/channels/web/frontend/src/multi-session/sidebar/SidebarMenu.tsx", "jiuwenswarm/channels/web/frontend/src/multi-session/sidebar/sidebarMenuSchema.ts", "jiuwenswarm/channels/web/frontend/src/multi-session/sidebar/sidebarModel.ts", "jiuwenswarm/server/runtime/agent_adapter/team_helpers.py", "jiuwenswarm/agents/harness/team/team_manager.py", "jiuwenswarm/channels/tui/frontend/src/app-state.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/new.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/rename.ts", "jiuwenswarm/channels/tui/frontend/src/ui/app-screen.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/resume.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/rewind.ts", "jiuwenswarm/gateway/channel_manager/tui/tui_connect.py", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/sessions.ts", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/archivedTasks/ArchivedTasksSettings.tsx", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/archivedTasks/definition.ts", "jiuwenswarm/channels/web/frontend/src/features/historyPagination.ts", "jiuwenswarm/channels/web/frontend/src/App.tsx", "jiuwenswarm/channels/web/frontend/src/features/historyRecordReassembler.ts", "jiuwenswarm/gateway/channel_manager/web/lifecycle_handlers.py", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/index.tsx", "jiuwenswarm/channels/web/frontend/src/multi-session/dialogs/Dialogs.tsx", "jiuwenswarm/channels/web/frontend/src/multi-session/dialogs/dialogs.css", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/projectSelection.ts", "jiuwenswarm/channels/web/frontend/src/types/index.ts", "jiuwenswarm/channels/web/frontend/src/features/teamHistoryPanelRestore.ts", "jiuwenswarm/channels/web/frontend/src/stores/workspaceStore.ts", "jiuwenswarm/channels/browser/frontend/src/webview/chat.html", "jiuwenswarm/channels/web/frontend/src/features/workspace/workModeStorage.ts", "jiuwenswarm/common/work_mode.py"]
 ---
 
 # 项目、会话与历史管理 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/agent-runtime/feature-runtime-agent-definition-execution.md b/knowledge/repos/jiuwenswarm/components/agent-runtime/feature-runtime-agent-definition-execution.md
new file mode 100644
index 00000000..7b5953df
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/agent-runtime/feature-runtime-agent-definition-execution.md
@@ -0,0 +1,54 @@
+---
+title: "声明式 root Agent 定义执行（invoke_agent/stream_agent）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/service.py:L1258-L1308, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/agent_definition.py:L37-L64, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/agent_definition.py:L3-L8, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/service.py:L1166-L1197, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/service.py:L1209-L1234, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/service.py:L1050-L1073, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/service.py:L1209-L1256, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/agent_definition.py:L276-L286, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/agent_definition.py:L159-L166, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/agent_definition.py:L233-L247, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/agent_definition.py:L265-L271, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/agent_definition.py:L21-L34, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/agent_definition.py:L103-L135, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/agent_definition.py:L194-L203]
+feature: "runtime-agent-definition-execution"
+entry_points: ["jiuwenswarm/runtime/service.py"]
+source_globs: ["jiuwenswarm/runtime/service.py", "jiuwenswarm/runtime/agent_definition.py"]
+---
+
+# 声明式 root Agent 定义执行（invoke_agent/stream_agent）
+
+<!-- kb:knowledge owner=feature-runtime-agent-definition-execution facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**公共入口与输入输出**
+
+`AgentRuntime.invoke_agent` 与 `stream_agent` 是声明式 root Agent 的两个公共入口：接收一个 `AgentRequest` 加上 `RuntimeAgentDefinition` 或普通 Mapping 形式的定义，分别返回 `list[RuntimeEvent]` 和异步迭代 `RuntimeEvent` 的流。两者都支持 `trigger_hook` 与 `on_control_event` 回调，`stream_agent` 额外提供 `on_agent_ready`。入口内部依次执行 start、会话归属校验、按请求参数里的 mode 做能力解析、定义校验、请求改写和 owner 绑定，然后把 `_agent_execution` 透传给既有的 `invoke`/`stream` 链路。定义或会话冲突通过 `RuntimeAgentDefinitionError`（`ValueError` 子类，`retryable=False`）抛出，携带稳定错误码与出错字段。
+
+Sources / 来源：[jiuwenswarm/runtime/service.py:L1258–L1308](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/service.py#L1258-L1308), [jiuwenswarm/runtime/agent_definition.py:L37–L64](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/agent_definition.py#L37-L64)
+
+<!-- kb:knowledge owner=feature-runtime-agent-definition-execution facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**职责边界与数据流**
+
+模块分工明确：`agent_definition.py` 只做传输无关的声明式输入校验（模块文档声明它不依赖 Process CLI 协议、transport 或 Agent 实现），产出 `RuntimeAgentDefinition`/`RuntimeAgentExecution` 能力契约；`AgentRuntime` 负责把这个契约翻译进既有执行链。执行路径上，`_bind_agent_execution_request` 把校验后的定义改写进请求参数（`mode` 设为 execution.mode、`work_mode` 固定为 `"code"`、可选解析 `model_name`），`_claim_agent_execution_owner` 以 `(channel_id, session_id)` 为键把定义指纹钉在 Runtime 生命周期内；随后 `_prepare_chat_turn` 把 `agent_definition` 与指纹作为 kwargs 传入会话准备，最终仍走 `invoke`/`stream` 的 AgentManager 与 Agent Adapter。
+
+Sources / 来源：[jiuwenswarm/runtime/agent_definition.py:L3–L8](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/agent_definition.py#L3-L8), [jiuwenswarm/runtime/service.py:L1166–L1197](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/service.py#L1166-L1197), [jiuwenswarm/runtime/service.py:L1209–L1234](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/service.py#L1209-L1234), [jiuwenswarm/runtime/service.py:L1050–L1073](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/service.py#L1050-L1073)
+
+<!-- kb:knowledge owner=feature-runtime-agent-definition-execution facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的执行行为与会话绑定**
+
+`invoke_agent`/`stream_agent` 在执行前先 `start()`、校验会话归属，再按请求 params 中的 mode 解析能力并 `validate_agent_definition`，随后把定义绑定为请求改写：`_bind_agent_execution_request` 要求请求是 chat.send 且 params 为 dict（否则 `INVALID_REQUEST`），否则覆盖 `mode` 为 execution.mode、`work_mode` 固定为 `"code"`，定义指定 model 时解析为 `model_name`（service.py:L1166–L1197）。模式层面，`RuntimeAgentExecution.__post_init__` 拒绝 `agent.work.normal`/`agent.work.plan`，抛 `UNSUPPORTED_MODE`（agent_definition.py:L276–L286）。会话绑定以 `(channel_id, session_id)` 为键：已存在绑定且指纹不同则抛 `SESSION_CONFLICT`，指纹相同则复用；`_forget_agent_execution_owner` 可按 channel/session 移除绑定（service.py:L1209–L1256）。
+
+Sources / 来源：[jiuwenswarm/runtime/service.py:L1258–L1308](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/service.py#L1258-L1308), [jiuwenswarm/runtime/service.py:L1166–L1197](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/service.py#L1166-L1197), [jiuwenswarm/runtime/service.py:L1209–L1256](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/service.py#L1209-L1256), [jiuwenswarm/runtime/agent_definition.py:L276–L286](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/agent_definition.py#L276-L286)
+
+<!-- kb:knowledge owner=feature-runtime-agent-definition-execution facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**显式拒绝 allowlist 与复用既有执行链**
+
+两个有文档依据的取舍：(1) 显式工具 allowlist 被有意拒绝——`RuntimeAgentDefinition` 的 docstring 写明 "An explicit allowlist is intentionally rejected until the Runtime can enforce it after all rails and extensions have contributed their tools"（agent_definition.py:L161–L166），即在全部 rails/extensions 贡献工具之前无法可靠执行 allowlist，因此 `tools='*'` 表示使用 Runtime 配置的工具集。(2) `RuntimeAgentExecution` 自述为 "a capability contract, not a second executor"：AgentRuntime 把它翻译为既有的 AgentManager/Agent Adapter 输入，避免第二套执行路径（agent_definition.py:L265–L271）。定义指纹是对 schema+canonical JSON 的 SHA-256，作为绑定一致性比较的稳定键（L233–L247）。
+
+Sources / 来源：[jiuwenswarm/runtime/agent_definition.py:L159–L166](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/agent_definition.py#L159-L166), [jiuwenswarm/runtime/agent_definition.py:L233–L247](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/agent_definition.py#L233-L247), [jiuwenswarm/runtime/agent_definition.py:L265–L271](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/agent_definition.py#L265-L271)
+
+<!-- kb:knowledge owner=feature-runtime-agent-definition-execution facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**定义字段与请求改写配置**
+
+`RuntimeAgentDefinition.from_mapping` 接受严格字段集 name/instructions/description/model/tools/skills/max_iterations（缺 name 或 instructions 报 INVALID_DEFINITION）。tools 默认 `"*"`；显式工具 allowlist 被拒绝（TOOL_ALLOWLIST_UNSUPPORTED），注意序列条目会先经过重复/空/非字符串校验。执行时 `_bind_agent_execution_request` 把请求 params 的 mode 覆盖为 execution.mode、work_mode 固定为 `"code"`，定义带 model 时经 `resolve_model_capability` 写入 `model_name`。max_iterations 可为 None，非 None 时须为正整数。
+
+Sources / 来源：[jiuwenswarm/runtime/agent_definition.py:L21–L34](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/agent_definition.py#L21-L34), [jiuwenswarm/runtime/agent_definition.py:L103–L135](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/agent_definition.py#L103-L135), [jiuwenswarm/runtime/service.py:L1166–L1197](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/service.py#L1166-L1197), [jiuwenswarm/runtime/agent_definition.py:L194–L203](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/agent_definition.py#L194-L203)
+
diff --git a/knowledge/repos/jiuwenswarm/components/agent-runtime/feature-session-input-steering.md b/knowledge/repos/jiuwenswarm/components/agent-runtime/feature-session-input-steering.md
new file mode 100644
index 00000000..812e7434
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/agent-runtime/feature-session-input-steering.md
@@ -0,0 +1,64 @@
+---
+title: "会话输入通道（steer/follow_up）与执行绑定 — 知识页"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/service.py:L1747-L1761, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/session_input.py:L15-L30, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/service.py:L2155-L2162, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/service.py:L1775-L1815, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/service.py:L1816-L1839, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/session_input.py:L33-L55, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/session_input.py:L58-L73, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/session_input.py:L10-L12, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/service.py:L1808-L1815, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/session_input.py:L68-L73, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/session_input.py:L21-L24, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/service.py:L1779-L1806, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:tests/unit_tests/runtime/test_session_input.py:L106-L132, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:tests/unit_tests/runtime/test_session_input.py:L259-L274, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:tests/unit_tests/runtime/test_session_input.py:L279-L299, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:tests/unit_tests/agentserver/test_session_input_adapter.py:L167-L229]
+feature: "session-input-steering"
+entry_points: ["jiuwenswarm/runtime/service.py"]
+source_globs: ["jiuwenswarm/runtime/service.py", "jiuwenswarm/runtime/session_input.py"]
+---
+
+# 会话输入通道（steer/follow_up）与执行绑定 — 知识页
+
+<!-- kb:knowledge owner=feature-session-input-steering facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**入口与错误契约**
+
+会话输入通过 `Runtime.stream()` 进入：当请求被判定为 session input（`_is_session_input_request`）时，先调用 `validate_session_input(request.params)` 做参数校验，随后执行一组前置检查——禁止后台投递（抛 `ValueError`）、要求跨会话准入（`_require_cross_session_input_admission`）、要求带 `session_id` 的受支持单 Agent Session（否则 `ValueError`），且会话快照不属于本 Runtime 或处于 CLOSED/QUIESCING 时抛 `RuntimeStateError`。另有独立的 `SessionInputRejectedError` 异常族（含 `SESSION_INPUT_TARGET_CHANGED`、`SESSION_INPUT_QUEUE_REQUIRED` 两个子类），文档字符串将其描述为"入队前已知的拒绝"；所示片段中仅证明该族存在及 `_stream_session_input_started` 引用了它。
+
+Sources / 来源：[jiuwenswarm/runtime/service.py:L1747–L1761](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/service.py#L1747-L1761), [jiuwenswarm/runtime/session_input.py:L15–L30](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/session_input.py#L15-L30), [jiuwenswarm/runtime/service.py:L2155–L2162](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/service.py#L2155-L2162)
+
+<!-- kb:knowledge owner=feature-session-input-steering facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**投递路径与控制流**
+
+`stream()` 按会话工作类型分流：session input 走 `_session_coordinator.stream_session_input(...)`，并传入 `idle_input` 回调、`suspension_key=self._waiting_control_id` 以及 `expected_execution_id`（来自 `request.params`）；普通工作在 `work_kind` 非空时经 `run_stream(...)`，`work_kind` 为空时直接 `_stream_started(...)`。`runtime.accepted`（`input_delivery: "chat"`）仅在 `idle_input` 回调的流式分支中、先于普通输出发出；非流式请求则在该回调中走 `_invoke_started` 保留单一最终响应。
+
+Sources / 来源：[jiuwenswarm/runtime/service.py:L1775–L1815](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/service.py#L1775-L1815), [jiuwenswarm/runtime/service.py:L1816–L1839](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/service.py#L1816-L1839)
+
+<!-- kb:knowledge owner=feature-session-input-steering facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**请求参数约定**
+
+意图模式由 `resolve_session_input_mode` 从 params 的 `input_mode` / `runtime_mode`（旧别名）归一化读取：两者同为真值且归一化后不一致时抛 `ValueError`；未知值返回 `None`，保留普通发送行为而非报错。`validate_session_input` 要求：`expected_execution_id` 若出现必须是非空字符串且仅在 steer 模式下允许；`query` 必须是非空文本；steer 模式下 `images/files/attachments/audio_files/video_files` 等真值字段直接拒绝。
+
+Sources / 来源：[jiuwenswarm/runtime/session_input.py:L33–L55](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/session_input.py#L33-L55), [jiuwenswarm/runtime/session_input.py:L58–L73](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/session_input.py#L58-L73)
+
+<!-- kb:knowledge owner=feature-session-input-steering facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的行为**
+
+支持两种输入意图：`SessionInputMode.STEER`（"steer"）与 `FOLLOW_UP`（"follow_up"）。steer 仅接受文本——注释解释为锁定 SDK 的主动转向队列只承载文本，附件应作为排队任务发送；带附件的 steer 请求在校验层被拒绝。执行绑定通过 `params["expected_execution_id"]` 表达，校验层限制其仅配 steer 模式使用，并在 `stream_session_input` 调用中作为 `expected_execution_id` 传入会话协调器（所示片段未展示协调器内部如何强制该绑定）。
+
+Sources / 来源：[jiuwenswarm/runtime/session_input.py:L10–L12](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/session_input.py#L10-L12), [jiuwenswarm/runtime/session_input.py:L58–L73](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/session_input.py#L58-L73), [jiuwenswarm/runtime/service.py:L1808–L1815](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/service.py#L1808-L1815)
+
+<!-- kb:knowledge owner=feature-session-input-steering facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**取舍**
+
+Inference / 设计推断（非作者历史意图）：
+
+代码显式体现了两个约束性选择：其一，steer 请求携带附件时立即抛错，而不是接受一个会被 SDK 队列静默丢弃的附件（注释原文："Never acknowledge an attachment which that queue would silently discard"）——即以显式失败换取可观测性（此概括为 inference）。其二，`SessionInputTargetError` 的文档字符串规定补充输入"绝不能成为另一个执行的工作"，即执行绑定的正确性优先于宽松投递。此外流式客户端先收到 idle disposition（`runtime.accepted`）再收普通输出，而非流式客户端保留单一最终响应，这是对两种客户端形态的分别适配。
+
+Sources / 来源：[jiuwenswarm/runtime/session_input.py:L68–L73](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/session_input.py#L68-L73), [jiuwenswarm/runtime/session_input.py:L21–L24](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/session_input.py#L21-L24), [jiuwenswarm/runtime/service.py:L1779–L1806](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/service.py#L1779-L1806)
+
+<!-- kb:knowledge owner=feature-session-input-steering facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**测试入口与覆盖**
+
+运行时层的行为由 `tests/unit_tests/runtime/test_session_input.py` 驱动 `AgentRuntime.stream()`/`invoke()` 覆盖：繁忙会话中补充输入绕过占用通道并作为 `SESSION_INPUT` 子执行挂到根执行上（`test_new_input_bypasses_busy_lane_without_answer_or_second_agent`）；`expected_execution_id` 绑定返回目标执行 ID 且不新建 CHAT_STREAM 执行，目标已结束或已切换时抛 "targeted execution has ended or changed" 且不产生副作用（`test_bound_input_keeps_original_execution_and_returns_its_id`、`test_bound_input_never_falls_back_or_targets_replacement`）；另有跨会话/受保护模式拒绝（`SessionInputQueueRequiredError`）、校验失败不派发（`ValueError`、模式冲突 "must agree"）、非本 Runtime 会话 `RuntimeStateError`、会话关闭取消在途输入等用例。适配器层由 `tests/unit_tests/agentserver/test_session_input_adapter.py` 直接调用 `JiuWenSwarmDeepAdapter.deliver_active_session_input`，配合真实 `LoopQueues` 验证 steer 文本经 `drain_steering()` 入队、竞态（执行结束/换轮/取消/跨会话/队列缺失）下 "not sent" 且队列为空，以及回执边界失败映射为 `SessionInputDeliveryUnknown`。测试上下文注明这些用例未在此环境中执行。
+
+Sources / 来源：[tests/unit_tests/runtime/test_session_input.py:L106–L132](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/tests/unit_tests/runtime/test_session_input.py#L106-L132), [tests/unit_tests/runtime/test_session_input.py:L259–L274](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/tests/unit_tests/runtime/test_session_input.py#L259-L274), [tests/unit_tests/runtime/test_session_input.py:L279–L299](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/tests/unit_tests/runtime/test_session_input.py#L279-L299), [tests/unit_tests/agentserver/test_session_input_adapter.py:L167–L229](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/tests/unit_tests/agentserver/test_session_input_adapter.py#L167-L229)
+
diff --git a/knowledge/repos/jiuwenswarm/components/agent-runtime/knowledge.md b/knowledge/repos/jiuwenswarm/components/agent-runtime/knowledge.md
new file mode 100644
index 00000000..3462d1fd
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/agent-runtime/knowledge.md
@@ -0,0 +1,43 @@
+---
+title: "共享 Agent 运行时（jiuwenswarm/runtime/service.py AgentRuntime）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/service.py:L3-L8, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/service.py:L296-L328, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/service.py:L791-L829, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/service.py:L613-L659, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:.doc_project_maintainer/modules/runtime-session/README.md:L19-L22, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/service.py:L296-L305, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/service.py:L881-L939, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/service.py:L941-L976, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/service.py:L1762-L1839, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/service.py:L307-L346, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/service.py:L486-L518, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/service.py:L204-L262, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/service.py:L547-L601]
+---
+
+# 共享 Agent 运行时（jiuwenswarm/runtime/service.py AgentRuntime）
+
+<!-- kb:knowledge owner=agent-runtime facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**传输无关的 Runtime 生命周期所有者**
+
+AgentRuntime 是共享 Agent 运行时的生命周期所有者：它持有唯一的 AgentManager、PlanModeController、RuntimeSessionProvisioner 和 RuntimeSessionCoordinator，模块文档明确声明它不承载任何传输关注点——AgentServer 与进程式 CLI 各自拥有一份实例并调用其公共操作，WebSocket 帧仍留在 AgentServer。类文档还规定它是 one-shot 的：close 之后不可再次 start，未终态的 PreparedSessionProvision 会在 close 前被拒绝，避免 finalizer 运行在已拆除的 Runtime 上。
+
+Sources / 来源：[jiuwenswarm/runtime/service.py:L3–L8](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/service.py#L3-L8), [jiuwenswarm/runtime/service.py:L296–L328](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/service.py#L296-L328)
+
+<!-- kb:knowledge owner=agent-runtime facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**跨会话消息与能力目录**
+
+send_session_message 从持久化元数据解析源/目标会话，要求目标有 channel、属同一 user（否则 PermissionError）、且为 Work/Code Normal 模式，未加载的目标会幂等恢复注册，然后以 SESSION_MESSAGE 工作类型异步排队并返回执行快照——文档说明其异步性是为了避免两会话互等模型执行而死锁。Runtime 还提供模型/模式目录（list/resolve_model_capability、list/resolve_mode_capability）、权限快照与本地 MCP 名称校验，均要求已 start。
+
+Sources / 来源：[jiuwenswarm/runtime/service.py:L791–L829](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/service.py#L791-L829), [jiuwenswarm/runtime/service.py:L613–L659](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/service.py#L613-L659), [.doc_project_maintainer/modules/runtime-session/README.md:L19–L22](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/.doc_project_maintainer/modules/runtime-session/README.md#L19-L22)
+
+<!-- kb:knowledge owner=agent-runtime facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**公共入口：预置事务与执行路由**
+
+AgentRuntime 是一次性生命周期拥有者：进程式 CLI 每条命令一份、AgentServer 服务生命期一份；close 后不可重启，close 拒绝尚未 commit/abort 的预置事务。prepare_session_create/switch/fork 在 lifecycle 锁内只做计数与 started 检查，真正的 provisioner 调用在锁外执行，prepared 对象在 finally 中加入 _pending_session_provisions；commit_session_provision 仅当结果是 SessionCreateResult 或 SessionSwitchResult 且模式为单 Agent（Work/Code Normal）时才注册会话，fork 结果不注册。执行入口 invoke/stream 先用 session_work_kind 分类：CONTROL_INPUT 走 _deliver_control，SESSION_INPUT 走 stream_session_input，其余有 work kind 的走协调器 run_unary/run_stream，没有 work kind 的请求绕过协调器直接执行。
+
+Sources / 来源：[jiuwenswarm/runtime/service.py:L296–L305](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/service.py#L296-L305), [jiuwenswarm/runtime/service.py:L881–L939](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/service.py#L881-L939), [jiuwenswarm/runtime/service.py:L941–L976](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/service.py#L941-L976), [jiuwenswarm/runtime/service.py:L1762–L1839](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/service.py#L1762-L1839)
+
+<!-- kb:knowledge owner=agent-runtime facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**构造参数决定进程依赖与扩展的归属**
+
+构造注入决定进程级依赖管理：initializer 为 None 时（默认）_manage_runner 与 _initialize_extensions 均为 True，start() 会获取进程全局 checkpointer/Runner 并初始化扩展；传入自定义 initializer 则只调用该 initializer，不再管理 Runner 与扩展。扩展获取分两种情形：当前不存在 ExtensionRegistry 实例时创建 registry 与 ExtensionManager 并 load_all_extensions（不含传输扩展）；若 AgentServer/Gateway 已预加载 registry，则仅借用该实例并返回 False，不参与其生命周期、也不加载扩展。模型目录方面，get_default_models 抛错时抛 ModelCatalogError("model catalog is unavailable", code="MODEL_CATALOG_UNAVAILABLE", retryable=True)；条目无法通过 build_model_from_entry 构造时按原位跳过，避免目录选择静默落到 Adapter 默认模型。
+
+Sources / 来源：[jiuwenswarm/runtime/service.py:L307–L346](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/service.py#L307-L346), [jiuwenswarm/runtime/service.py:L486–L518](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/service.py#L486-L518), [jiuwenswarm/runtime/service.py:L204–L262](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/service.py#L204-L262), [jiuwenswarm/runtime/service.py:L547–L601](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/service.py#L547-L601)
+
diff --git a/knowledge/repos/jiuwenswarm/components/agent-runtime/source-contracts-01.md b/knowledge/repos/jiuwenswarm/components/agent-runtime/source-contracts-01.md
index 23e601ce..ab8cbe4a 100644
--- a/knowledge/repos/jiuwenswarm/components/agent-runtime/source-contracts-01.md
+++ b/knowledge/repos/jiuwenswarm/components/agent-runtime/source-contracts-01.md
@@ -1,7 +1,7 @@
 ---
 title: "agent-runtime 源码接口与集成边界 01"
 created: 2026-10-01
-updated: 2026-10-01
+updated: 2026-10-06
 type: architecture
 tags: [jiuwenswarm]
 sources: []
@@ -163,3 +163,12 @@ sources: []
 
 源码依据：[完整声明与实现](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/session_delete.py#L1-L146)。
 <!-- /kb:file -->
+
+<!-- kb:file path=jiuwenswarm/runtime/__init__.py pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b sha256=c71aec5d3acb97a6168baffce58220a3ea789ef708886f5231c256b3c2f2e84e -->
+**`jiuwenswarm/runtime/__init__.py`**
+
+- 源码对模块职责的说明：Lazy public surface for the transport-independent JiuwenSwarm Runtime.。
+- 集成依赖（导入声明，不等于全部运行时依赖）：`from __future__ import annotations`；`from importlib import import_module`；`from typing import TYPE_CHECKING, Any`。
+
+源码依据：[完整声明与实现](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/__init__.py#L1-L36)。
+<!-- /kb:file -->
diff --git a/knowledge/repos/jiuwenswarm/components/agent-server-runtime/_index.md b/knowledge/repos/jiuwenswarm/components/agent-server-runtime/_index.md
index 7556dd42..f94c0c21 100644
--- a/knowledge/repos/jiuwenswarm/components/agent-server-runtime/_index.md
+++ b/knowledge/repos/jiuwenswarm/components/agent-server-runtime/_index.md
@@ -57,3 +57,4 @@ sources: []
 - [主动推荐、频率限制与主 Agent 交付：实现深读](feature-depth-proactive-recommendation.md)
 
 - [Skill 自演进：实现深读](feature-depth-skill-evolution.md)
+- [Workspace Git Diff 聚合（get_git_diff）与实时监控](feature-workspace-git-diff.md)
diff --git a/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-coding-memory.md b/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-coding-memory.md
index 13915682..10014f6b 100644
--- a/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-coding-memory.md
+++ b/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-coding-memory.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/编码记忆.md
 feature: "coding-memory"
 entry_points: ["jiuwenswarm/server/runtime/agent_adapter/interface_code.py"]
-source_globs: ["jiuwenswarm/server/runtime/agent_adapter/interface_code.py", "jiuwenswarm/agents/harness/code/*"]
+source_globs: ["jiuwenswarm/server/runtime/agent_adapter/interface_code.py", "jiuwenswarm/agents/harness/code/*", "jiuwenswarm/common/coding_memory_paths.py", "jiuwenswarm/agents/harness/common/rails/project_memory/__init__.py", "jiuwenswarm/agents/harness/common/rails/project_memory/files.py", "jiuwenswarm/agents/harness/common/rails/project_memory_rail.py", "jiuwenswarm/agents/harness/common/rails/project_memory/section.py"]
 ---
 
 # Code 模式编码记忆 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-context.md b/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-context.md
index fe2493dc..457d9cd9 100644
--- a/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-context.md
+++ b/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-context.md
@@ -11,7 +11,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/上下文压缩.md
 feature: "context"
 entry_points: ["jiuwenswarm/server/runtime/agent_adapter/compact_partial_prompts.py", "jiuwenswarm/server/runtime/agent_adapter/interface_deep.py"]
-source_globs: ["jiuwenswarm/server/runtime/agent_adapter/compact_partial_prompts.py", "jiuwenswarm/server/runtime/agent_adapter/interface_deep.py", "jiuwenswarm/agents/harness/common/*"]
+source_globs: ["jiuwenswarm/server/runtime/agent_adapter/compact_partial_prompts.py", "jiuwenswarm/server/runtime/agent_adapter/interface_deep.py", "jiuwenswarm/agents/harness/common/*", "jiuwenswarm/channels/ide/packages/shared-webview/chat.html", "jiuwenswarm/server/agent_ws_server.py", "jiuwenswarm/server/runtime/agent_adapter/interface.py", "jiuwenswarm/server/runtime/tokenizer_service.py", "jiuwenswarm/channels/web/frontend/src/components/SessionSidebar/OffloadFilesWidget.tsx"]
 ---
 
 # 上下文压缩与卸载 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-harness.md b/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-harness.md
index 978719c6..d0d99c1b 100644
--- a/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-harness.md
+++ b/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-harness.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/Harness.md
 feature: "harness"
 entry_points: ["jiuwenswarm/server/runtime/agent_adapter/interface_deep.py"]
-source_globs: ["jiuwenswarm/server/runtime/agent_adapter/interface_deep.py", "jiuwenswarm/agents/harness/common/rails/*"]
+source_globs: ["jiuwenswarm/server/runtime/agent_adapter/interface_deep.py", "jiuwenswarm/agents/harness/common/rails/*", "jiuwenswarm/agents/harness/common/rails/avatar_rail.py", "jiuwenswarm/runtime/service.py", "jiuwenswarm/agents/harness/common/rails/execution_guard/circuit_breaker_rail.py", "jiuwenswarm/server/runtime/agent_adapter/interface_code.py", "jiuwenswarm/agents/harness/code/rails/__init__.py", "jiuwenswarm/agents/harness/code/rails/code_agent_mode_rail.py", "jiuwenswarm/agents/harness/code/prompt/__init__.py", "jiuwenswarm/agents/harness/code/prompt/code_prompt_builder.py", "jiuwenswarm/agents/harness/code/spec.py", "jiuwenswarm/agents/harness/common/rails/runtime_prompt_rail.py", "jiuwenswarm/agents/harness/common/prompt/prompt_builder.py", "jiuwenswarm/agents/harness/common/tools/__init__.py", "jiuwenswarm/server/runtime/agent_adapter/interface.py", "jiuwenswarm/agents/harness/common/rails/interrupt/interrupt_helpers.py", "jiuwenswarm/agents/harness/common/rails/permissions/permission_interrupt_rail.py", "jiuwenswarm/server/agent_ws_server.py", "jiuwenswarm/agents/harness/common/tools/mcp_toolkits.py", "jiuwenswarm/agents/harness/common/rails/permissions/network_scope.py", "jiuwenswarm/server/runtime/agent_adapter/output_handoff.py", "jiuwenswarm/agents/harness/common/rails/permissions/permission_interaction.py", "jiuwenswarm/server/runtime/agent_adapter/permission_rail_group.py", "jiuwenswarm/common/permission_tools.py", "jiuwenswarm/agents/harness/common/rails/__init__.py", "jiuwenswarm/agents/harness/common/plugins/rail_manager.py", "jiuwenswarm/agents/harness/common/rails/response_prompt_rail.py", "jiuwenswarm/runtime/events.py", "jiuwenswarm/runtime/context.py", "jiuwenswarm/runtime/host_services.py", "jiuwenswarm/runtime/interaction.py", "jiuwenswarm/runtime/session/coordinator.py", "jiuwenswarm/server/runtime/session/session_manager.py", "jiuwenswarm/runtime/session/work_scheduler.py", "jiuwenswarm/agents/harness/common/prompt/shell_environment.py", "jiuwenswarm/agents/harness/common/rails/stream_event_rail.py", "jiuwenswarm/agents/swarm/providers/builtin_rails.py", "jiuwenswarm/agents/swarm/providers/code_rails.py", "jiuwenswarm/agents/harness/team/team_manager.py", "jiuwenswarm/agents/swarm/providers/member_rails.py", "jiuwenswarm/agents/swarm/registry.py", "jiuwenswarm/agents/swarm/providers/runtime_tools.py", "jiuwenswarm/agents/swarm/config_specs.py", "jiuwenswarm/agents/swarm/providers/code_subagents.py", "jiuwenswarm/agents/harness/common/rails/symphony/retrieval_context_processor.py", "jiuwenswarm/agents/harness/common/rails/symphony/tool_stream_events.py", "jiuwenswarm/agents/harness/common/prompt/priority_registry.py", "jiuwenswarm/agents/harness/team/team_runtime_inheritance.py", "jiuwenswarm/agents/harness/common/rails/permissions/tool_binding.py", "jiuwenswarm/agents/harness/common/rails/permissions/_auto_permission/invocation_context.py", "jiuwenswarm/agents/harness/common/rails/permissions/tool_permission_context.py", "jiuwenswarm/agents/harness/common/tool_progress_context.py", "jiuwenswarm/agents/harness/work/prompt/work_plan_prompts.py"]
 ---
 
 # Agent Loop 与 Rail 装配 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-heartbeat.md b/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-heartbeat.md
index c593c4a8..0d3be7f4 100644
--- a/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-heartbeat.md
+++ b/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-heartbeat.md
@@ -13,7 +13,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/AGENTS.md
 feature: "heartbeat"
 entry_points: ["jiuwenswarm/agents/harness/code/rails/heartbeat/models.py", "jiuwenswarm/agents/harness/code/rails/heartbeat/controller.py", "jiuwenswarm/gateway/heartbeat/proxy.py"]
-source_globs: ["jiuwenswarm/agents/harness/code/rails/heartbeat/models.py", "jiuwenswarm/agents/harness/code/rails/heartbeat/controller.py", "jiuwenswarm/gateway/heartbeat/proxy.py"]
+source_globs: ["jiuwenswarm/agents/harness/code/rails/heartbeat/models.py", "jiuwenswarm/agents/harness/code/rails/heartbeat/controller.py", "jiuwenswarm/gateway/heartbeat/proxy.py", "jiuwenswarm/agents/harness/code/rails/heartbeat/tools.py", "jiuwenswarm/channels/web/frontend/src/utils/heartbeatAutomation.ts", "jiuwenswarm/agents/harness/code/rails/heartbeat/cron_schedule.py", "jiuwenswarm/agents/harness/code/rails/heartbeat/execution.py", "jiuwenswarm/channels/web/frontend/src/types/heartbeat.ts", "jiuwenswarm/agents/harness/code/rails/heartbeat/__init__.py", "jiuwenswarm/server/agent_ws_server.py", "jiuwenswarm/agents/harness/code/rails/heartbeat/store.py", "jiuwenswarm/channels/web/frontend/src/components/HeartbeatPanel/HeartbeatPagination.tsx", "jiuwenswarm/agents/harness/code/rails/heartbeat_rail.py", "jiuwenswarm/agents/harness/code/rails/heartbeat/runtime.py", "jiuwenswarm/runtime/service.py", "jiuwenswarm/agents/harness/code/rails/heartbeat/scheduler.py", "jiuwenswarm/agents/harness/code/rails/heartbeat/session_resolver.py", "jiuwenswarm/channels/web/frontend/src/components/HeartbeatPanel/HeartbeatStatusBadge.tsx", "jiuwenswarm/channels/web/frontend/src/components/HeartbeatPanel/heartbeatStatusText.ts", "jiuwenswarm/channels/web/frontend/src/components/HeartbeatPanel/index.tsx", "jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py", "jiuwenswarm/channels/web/frontend/src/components/HeartbeatPanel/HeartbeatScheduleEditor.tsx", "jiuwenswarm/channels/web/frontend/src/components/HeartbeatPanel/HeartbeatTaskDrawer.tsx", "jiuwenswarm/channels/web/frontend/src/components/HeartbeatPanel/heartbeatCronValidation.ts", "jiuwenswarm/channels/web/frontend/src/components/HeartbeatPanel/heartbeatScheduleConvert.ts", "jiuwenswarm/gateway/channel_manager/tui/tui_connect.py"]
 ---
 
 # 绑定会话的心跳续跑任务的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-modes.md b/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-modes.md
index b0b66ad4..bea9b3f4 100644
--- a/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-modes.md
+++ b/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-modes.md
@@ -11,7 +11,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/模式系统.md
 feature: "modes"
 entry_points: ["jiuwenswarm/runtime/mode_catalog.py", "jiuwenswarm/common/mode_matrix.py"]
-source_globs: ["jiuwenswarm/runtime/mode_catalog.py", "jiuwenswarm/common/mode_matrix.py", "jiuwenswarm/server/runtime/agent_adapter/*.py"]
+source_globs: ["jiuwenswarm/runtime/mode_catalog.py", "jiuwenswarm/common/mode_matrix.py", "jiuwenswarm/server/runtime/agent_adapter/*.py", "jiuwenswarm/server/runtime/agent_manager.py", "jiuwenswarm/runtime/request.py", "jiuwenswarm/server/agent_ws_server.py", "jiuwenswarm/agents/harness/code/rails/code_confirm_interrupt_rail.py", "jiuwenswarm/channels/web/frontend/src/features/code-mode/gitPublishState.ts", "jiuwenswarm/channels/web/frontend/src/features/planMode/wireMode.ts", "jiuwenswarm/server/runtime/tenant_agent_pool.py", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/mode.ts", "jiuwenswarm/channels/tui/frontend/src/ui/app-screen.ts", "jiuwenswarm/channels/tui/frontend/src/core/event-handlers.ts", "jiuwenswarm/server/runtime/agent_adapter/user_turn.py", "jiuwenswarm/channels/web/frontend/src/config/chatConfig.tsx", "jiuwenswarm/channels/web/frontend/src/config/permissionProfiles.ts", "jiuwenswarm/server/runtime/session/work_mode.py"]
 ---
 
 # Agent、Code 与 Team 模式 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-permissions.md b/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-permissions.md
index 0ce22530..b86fda5d 100644
--- a/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-permissions.md
+++ b/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-permissions.md
@@ -11,7 +11,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/工具权限与安全防护.md
 feature: "permissions"
 entry_points: ["jiuwenswarm/agents/harness/common/rails/permissions/permission_interrupt_rail.py", "jiuwenswarm/agents/harness/common/rails/permissions/policy_eval.py"]
-source_globs: ["jiuwenswarm/agents/harness/common/rails/permissions/permission_interrupt_rail.py", "jiuwenswarm/agents/harness/common/rails/permissions/policy_eval.py", "jiuwenswarm/server/*"]
+source_globs: ["jiuwenswarm/agents/harness/common/rails/permissions/permission_interrupt_rail.py", "jiuwenswarm/agents/harness/common/rails/permissions/policy_eval.py", "jiuwenswarm/server/*", "jiuwenswarm/channels/web/frontend/src/components/InteractionSlot/promptRouting.ts", "jiuwenswarm/agents/harness/common/rails/permissions/audit.py", "jiuwenswarm/agents/harness/common/rails/permissions/_auto_permission/before_tool.py", "jiuwenswarm/agents/harness/common/rails/permissions/auto_config.py", "jiuwenswarm/agents/harness/common/rails/permissions/auto_decision.py", "jiuwenswarm/agents/harness/common/rails/permissions/_auto_permission/deny_response.py", "jiuwenswarm/agents/harness/common/rails/permissions/_auto_permission/deterministic.py", "jiuwenswarm/agents/harness/common/rails/permissions/_auto_permission/domain_grant_audit.py", "jiuwenswarm/agents/harness/common/rails/permissions/_auto_permission/models.py", "jiuwenswarm/agents/harness/common/rails/permissions/persistent_audit.py", "jiuwenswarm/agents/harness/common/rails/permissions/auto_permission_rail.py", "jiuwenswarm/agents/harness/common/rails/permissions/_auto_permission/lifecycle.py", "jiuwenswarm/agents/harness/common/rails/permissions/_auto_permission/reviewer_execution.py", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/AutoReviewerStatus.tsx", "jiuwenswarm/channels/cli/_terminal.py", "jiuwenswarm/channels/cli/chat.py", "jiuwenswarm/server/agent_ws_server.py", "jiuwenswarm/common/config.py", "jiuwenswarm/agents/harness/common/tools/file_delivery_policy.py", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/InputArea.tsx", "jiuwenswarm/agents/harness/common/rails/permissions/_auto_permission/domain_manual.py", "jiuwenswarm/agents/harness/common/rails/permissions/_auto_permission/manual_authorization.py", "jiuwenswarm/agents/harness/common/rails/permissions/_auto_permission/invocation_context.py", "jiuwenswarm/agents/harness/common/rails/permissions/native_path_context.py", "jiuwenswarm/agents/harness/common/rails/permissions/__init__.py", "jiuwenswarm/agents/harness/common/rails/permissions/openjiuwen_contract.py", "jiuwenswarm/server/runtime/extension_package_manager.py", "jiuwenswarm/agents/harness/common/rails/permissions/permission_compose.py", "jiuwenswarm/server/runtime/agent_adapter/permission_continuation.py", "jiuwenswarm/agents/harness/common/rails/permissions/execution_provider_contract.py", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/PermissionWarningDialog.tsx", "jiuwenswarm/agents/harness/common/rails/permissions/permissions_layers.py", "jiuwenswarm/agents/harness/common/rails/interrupt/permission_options.py", "jiuwenswarm/agents/harness/common/rails/permissions/owner_scopes.py", "jiuwenswarm/agents/harness/common/rails/permissions/permissions_config_rpc.py", "jiuwenswarm/agents/harness/common/rails/permissions/permissions_persist.py", "jiuwenswarm/server/runtime/agent_manager.py", "jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py", "jiuwenswarm/agents/harness/common/rails/permissions/protected_paths.py", "jiuwenswarm/agents/harness/common/rails/permissions/_auto_permission/readonly_tool_bindings.py", "jiuwenswarm/agents/harness/common/rails/permissions/auto_reviewer.py", "jiuwenswarm/agents/harness/common/rails/permissions/_auto_permission/reviewer_audit.py", "jiuwenswarm/agents/harness/common/rails/permissions/_auto_permission/reviewer_override_consume.py", "jiuwenswarm/agents/harness/common/rails/permissions/_auto_permission/reviewer_override_gate.py", "jiuwenswarm/agents/harness/common/rails/permissions/reviewer_redaction.py", "jiuwenswarm/agents/harness/common/rails/permissions/reviewer_route.py", "jiuwenswarm/agents/harness/common/rails/permissions/reviewer_stream_metadata.py", "jiuwenswarm/agents/harness/common/rails/permissions/_auto_permission/reviewer_metadata.py", "jiuwenswarm/agents/harness/common/rails/permissions/root_ask_user.py", "jiuwenswarm/agents/harness/common/rails/permissions/root_context_rail.py", "jiuwenswarm/agents/harness/common/rails/permissions/root_context.py", "jiuwenswarm/agents/harness/common/rails/permissions/root_permission_queue.py", "jiuwenswarm/agents/harness/common/rails/permissions/root_permission_queue_rail.py", "jiuwenswarm/runtime/permission_catalog.py", "jiuwenswarm/agents/harness/common/rails/permissions/send_file_approval_scope.py", "jiuwenswarm/agents/harness/common/rails/permissions/send_file_path_guard.py", "jiuwenswarm/agents/harness/common/rails/permissions/session_deny.py", "jiuwenswarm/server/runtime/agent_adapter/permission_runtime_state.py", "jiuwenswarm/server/runtime/agent_adapter/interface_deep.py", "jiuwenswarm/agents/harness/common/tools/bash_tool_safety.py", "jiuwenswarm/agents/swarm/providers/member_rails.py", "jiuwenswarm/agents/harness/team/rails/team_permission_policy_rail.py", "jiuwenswarm/agents/harness/common/rails/permissions/tool_capabilities.py", "jiuwenswarm/agents/harness/common/rails/permissions/tool_decision_facts.py", "jiuwenswarm/agents/harness/common/rails/permissions/tool_invocation_key.py", "jiuwenswarm/agents/harness/common/rails/permissions/trusted_search_urls.py", "jiuwenswarm/channels/tui/frontend/src/ui/app-screen.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/permissions.ts", "jiuwenswarm/agents/harness/common/rails/permissions/url_safety.py", "jiuwenswarm/channels/web/frontend/src/components/InteractionSlot/AuthorizationPrompt.tsx", "jiuwenswarm/channels/web/frontend/src/components/InteractionSlot/InteractionSlot.css", "jiuwenswarm/agents/harness/common/workspace_paths.py", "jiuwenswarm/server/front/connection.py"]
 ---
 
 # 工具权限与安全治理 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-proactive-recommendation.md b/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-proactive-recommendation.md
index f289dab6..21cbb90d 100644
--- a/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-proactive-recommendation.md
+++ b/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-proactive-recommendation.md
@@ -11,7 +11,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/设置与频道升级迁移指南.md
 feature: "proactive-recommendation"
 entry_points: ["jiuwenswarm/agents/harness/common/recommendation/proactive_engine.py", "jiuwenswarm/server/runtime/proactive_adapter.py"]
-source_globs: ["jiuwenswarm/agents/harness/common/recommendation/proactive_engine.py", "jiuwenswarm/server/runtime/proactive_adapter.py"]
+source_globs: ["jiuwenswarm/agents/harness/common/recommendation/proactive_engine.py", "jiuwenswarm/server/runtime/proactive_adapter.py", "jiuwenswarm/agents/harness/common/recommendation/calendar_source.py", "jiuwenswarm/agents/harness/common/recommendation/proactive_actions.py", "jiuwenswarm/agents/harness/common/recommendation/feedback_collector.py", "jiuwenswarm/server/agent_ws_server.py", "jiuwenswarm/agents/harness/common/recommendation/gradient_updater.py", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/experimental/ExperimentalSettings.tsx", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/experimental/definition.ts", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ProactiveRecommendationCard.tsx", "jiuwenswarm/agents/harness/common/recommendation/__init__.py", "jiuwenswarm/server/runtime/agent_adapter/interface.py", "jiuwenswarm/agents/harness/common/recommendation/proactive_prompts.py", "jiuwenswarm/agents/harness/common/recommendation/profile_extractor.py", "jiuwenswarm/agents/harness/common/recommendation/situation_report.py", "jiuwenswarm/channels/web/frontend/src/App.tsx"]
 ---
 
 # 主动推荐、频率限制与主 Agent 交付的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-skill-development.md b/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-skill-development.md
index 6086fc4e..760a3383 100644
--- a/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-skill-development.md
+++ b/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-skill-development.md
@@ -13,7 +13,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/server/runtime/skill/skilldev/DESIGN.md
 feature: "skill-development"
 entry_points: ["jiuwenswarm/server/runtime/skill/skilldev/service.py", "jiuwenswarm/server/runtime/skill/skilldev/pipeline.py", "jiuwenswarm/server/runtime/skill/skilldev/deps.py", "jiuwenswarm/server/runtime/skill/skilldev/context.py"]
-source_globs: ["jiuwenswarm/server/runtime/skill/skilldev/service.py", "jiuwenswarm/server/runtime/skill/skilldev/pipeline.py", "jiuwenswarm/server/runtime/skill/skilldev/deps.py", "jiuwenswarm/server/runtime/skill/skilldev/context.py"]
+source_globs: ["jiuwenswarm/server/runtime/skill/skilldev/service.py", "jiuwenswarm/server/runtime/skill/skilldev/pipeline.py", "jiuwenswarm/server/runtime/skill/skilldev/deps.py", "jiuwenswarm/server/runtime/skill/skilldev/context.py", "jiuwenswarm/channels/web/frontend/src/components/SkillPanel/DocToSkillModal.tsx", "jiuwenswarm/resources/agent/workspace/skills/skill-creator-normal/scripts/aggregate_benchmark.py", "jiuwenswarm/resources/agent/workspace/skills/skill-creator-normal/eval-viewer/viewer.html", "jiuwenswarm/server/runtime/skill/skill_manager.py", "jiuwenswarm/resources/agent/workspace/skills/skill-creator-normal/scripts/improve_description.py", "jiuwenswarm/resources/agent/workspace/skills/skill-creator-normal/scripts/run_loop.py", "jiuwenswarm/resources/agent/workspace/skills/skill-creator-normal/scripts/run_eval.py", "jiuwenswarm/resources/agent/workspace/skills/skill-creator-normal/eval-viewer/generate_review.py", "jiuwenswarm/resources/agent/workspace/skills/skill-creator-normal/assets/eval_review.html", "jiuwenswarm/resources/agent/workspace/skills/skill-creator-normal/scripts/quick_validate.py", "jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/download_images.py", "jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/prepare_images.py", "jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/image_review.py", "jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/save_images.py", "jiuwenswarm/resources/agent/workspace/skills/skill-creator-normal/scripts/utils.py", "jiuwenswarm/resources/agent/workspace/skills/skill-creator-normal/scripts/generate_report.py", "jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/validator.py", "jiuwenswarm/resources/agent/workspace/skills/skill-creator-normal/scripts/package_skill.py", "jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/finalize_scripts.py", "jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/common.py", "jiuwenswarm/server/runtime/skill/skilldev/store.py", "jiuwenswarm/server/runtime/skill/skilldev/workspace.py", "jiuwenswarm/server/runtime/skill/skilldev/schema.py", "jiuwenswarm/server/runtime/skill/skilldev/stages/desc_optimize_stage.py", "jiuwenswarm/server/runtime/skill/skilldev/stages/evaluate_stage.py", "jiuwenswarm/server/runtime/skill/skilldev/stages/generate_stage.py", "jiuwenswarm/server/runtime/skill/skilldev/stages/improve_stage.py", "jiuwenswarm/server/runtime/skill/skilldev/stages/init_stage.py", "jiuwenswarm/server/runtime/skill/skilldev/stages/package_stage.py", "jiuwenswarm/server/runtime/skill/skilldev/stages/plan_stage.py", "jiuwenswarm/server/runtime/agent_adapter/interface.py", "jiuwenswarm/server/runtime/skill/skilldev/stages/validate_stage.py"]
 ---
 
 # SkillDev 创建、评测与打包边界的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-skill-evolution.md b/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-skill-evolution.md
index 6f900ee8..54030393 100644
--- a/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-skill-evolution.md
+++ b/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-skill-evolution.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/Skill自演进.md
 feature: "skill-evolution"
 entry_points: ["jiuwenswarm/server/runtime/agent_adapter/evolution_helpers.py"]
-source_globs: ["jiuwenswarm/server/runtime/agent_adapter/evolution_helpers.py", "jiuwenswarm/agents/harness/common/rails/*"]
+source_globs: ["jiuwenswarm/server/runtime/agent_adapter/evolution_helpers.py", "jiuwenswarm/agents/harness/common/rails/*", "jiuwenswarm/gateway/message_handler/evolution_approval.py", "jiuwenswarm/gateway/message_handler/message_handler.py", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/evolution-status.ts", "jiuwenswarm/server/runtime/agent_adapter/interface_deep.py", "jiuwenswarm/runtime/evolution.py", "jiuwenswarm/server/runtime/skill/skill_manager.py", "jiuwenswarm/channels/web/frontend/src/components/SkillPanel/useEvolution.ts", "jiuwenswarm/channels/web/frontend/src/features/SkillEvolutionModal/index.tsx", "jiuwenswarm/agents/swarm/providers/evolution_rails.py", "jiuwenswarm/server/runtime/agent_adapter/team_helpers.py", "jiuwenswarm/agents/harness/team/team_manager.py", "jiuwenswarm/channels/tui/frontend/src/app-state.ts"]
 ---
 
 # Skill 自演进 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-workspace-git-diff.md b/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-workspace-git-diff.md
new file mode 100644
index 00000000..9130be7a
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-workspace-git-diff.md
@@ -0,0 +1,56 @@
+---
+title: "Workspace Git Diff 聚合（get_git_diff）与实时监控"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/server/utils/diff_service.py:L2025-L2060, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/server/utils/diff_service.py:L2233-L2242, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/server/runtime/session/git_diff_status.py:L1-L8, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/server/utils/diff_service.py:L2061-L2130, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/server/runtime/session/git_diff_watcher.py:L1-L10, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/server/runtime/session/git_diff_watcher.py:L40-L50, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/server/runtime/session/git_diff_watcher.py:L270-L272, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/server/runtime/session/git_diff_watcher.py:L381-L386, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/server/runtime/session/git_diff_watcher.py:L23-L37, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/server/utils/diff_service.py:L2061-L2070, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/server/utils/diff_service.py:L1495-L1500, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/server/utils/diff_service.py:L1495-L1537, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/server/utils/diff_service.py:L2157-L2175, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/server/utils/diff_service.py:L1569-L1602]
+feature: "workspace-git-diff"
+entry_points: ["jiuwenswarm/server/utils/diff_service.py"]
+source_globs: ["jiuwenswarm/server/utils/diff_service.py", "jiuwenswarm/server/runtime/session/git_diff_watcher.py", "jiuwenswarm/server/runtime/session/git_diff_status.py"]
+---
+
+# Workspace Git Diff 聚合（get_git_diff）与实时监控
+
+<!-- kb:knowledge owner=feature-workspace-git-diff facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**get_git_diff 入口与返回契约**
+
+`DiffService.get_git_diff(project_dir, *, include_files=True, include_hunks=True, hunk_paths=None)` 返回工作区相对 HEAD 的 diff 聚合：`stats`（filesChanged/linesAdded/linesRemoved，filesChanged 为实际总数）、`files`（绝对路径到条目，含 hunks、isNewFile、isBinary、isLargeFile 等标志）、`files_truncated`/`files_limit` 预览截断提示；非 git 仓库、无改动或处于瞬态 git 状态时返回 `None`。Web 侧由 `DiffStatusService` 复用该结果并转换为 snake_case 的 `ProjectGitDiffStatus` schema（repo 元信息 + current 工作区摘要 + last_turn 对话轮摘要）。
+
+Sources / 来源：[jiuwenswarm/server/utils/diff_service.py:L2025–L2060](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/server/utils/diff_service.py#L2025-L2060), [jiuwenswarm/server/utils/diff_service.py:L2233–L2242](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/server/utils/diff_service.py#L2233-L2242), [jiuwenswarm/server/runtime/session/git_diff_status.py:L1–L8](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/server/runtime/session/git_diff_status.py#L1-L8)
+
+<!-- kb:knowledge owner=feature-workspace-git-diff facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**三层分层：服务计算、状态聚合、按项目聚合的实时推送**
+
+底层 `DiffService.get_git_diff` 依次执行：`git rev-parse --show-toplevel` 找仓库根、瞬态状态检测、`git diff HEAD --shortstat` 快速探测规模（超限仅返回统计）、`--numstat`/`--name-status`/`--porcelain=v1` 取逐文件统计与状态、按文件流式 `git diff` 解析 hunks，最后与 `_build_untracked_entries` 生成的 untracked 条目合并。其上 `DiffStatusService` 聚合 current 与 last_turn 两路来源；`GitDiffWatcherRegistry` 按 `project_id` 聚合 watcher，为每层维护 summary/files/detail 三个 fingerprint（MD5），变化时经 WebChannel 推送事件，`mark_dirty` 唤醒轮询、`cleanup_ws`/`cleanup_project` 释放资源。
+
+Sources / 来源：[jiuwenswarm/server/utils/diff_service.py:L2061–L2130](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/server/utils/diff_service.py#L2061-L2130), [jiuwenswarm/server/runtime/session/git_diff_watcher.py:L1–L10](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/server/runtime/session/git_diff_watcher.py#L1-L10), [jiuwenswarm/server/runtime/session/git_diff_watcher.py:L40–L50](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/server/runtime/session/git_diff_watcher.py#L40-L50)
+
+<!-- kb:knowledge owner=feature-workspace-git-diff facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**所示片段中的测试线索**
+
+Inference / 设计推断（非作者历史意图）：
+
+本次所示源码片段未包含测试文件本身，但 watcher 的接口注释提供了验证入口线索：`add_watch` 的 `on_initial=None` 分支注明"保留用于兼容已有测试与外部调用方"，`restore_files_state`/`restore_detail_state` 也注明保留为公开接口以兼容已有调用方与测试、新代码应优先使用带自动回滚的 `update_files_with_restore`/`update_detail_with_restore`。这表明存在针对 watcher 订阅生命周期的既有测试（具体用例文件未在本次输入中展示）。
+
+Sources / 来源：[jiuwenswarm/server/runtime/session/git_diff_watcher.py:L270–L272](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/server/runtime/session/git_diff_watcher.py#L270-L272), [jiuwenswarm/server/runtime/session/git_diff_watcher.py:L381–L386](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/server/runtime/session/git_diff_watcher.py#L381-L386)
+
+<!-- kb:knowledge owner=feature-workspace-git-diff facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**监控轮询常量与 diff 阈值**
+
+实时监控侧的行为由模块级常量控制：`POLL_INTERVAL_SEC = 2.0`（summary 轮询周期）、`DEBOUNCE_SEC = 0.3`（mark_dirty 后合并重算的最小等待）、`ERROR_BACKOFF_SEC = 5.0`（git 命令失败退避）、`MAX_PUSH_FAILURES = 3`（孤儿 watcher 自动回收阈值）；`NOT_GIT_REPOSITORY`/`PROJECT_DIR_MISSING` 被列为不可重试的结构性错误码。diff 计算侧引用 `MAX_DIFF_SIZE_BYTES`、`MAX_FILES`、`MAX_FILES_FOR_DETAILS`、`INTERNAL_UNTRACKED_DIRS` 等模块常量，但其数值未在所示片段中定义。`get_git_diff` 的 `include_hunks=True` 会经 `effective_include_files = include_files or include_hunks` 强制进入文件构造路径，即使 `include_files=False`。
+
+Sources / 来源：[jiuwenswarm/server/runtime/session/git_diff_watcher.py:L23–L37](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/server/runtime/session/git_diff_watcher.py#L23-L37), [jiuwenswarm/server/utils/diff_service.py:L2061–L2070](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/server/utils/diff_service.py#L2061-L2070), [jiuwenswarm/server/utils/diff_service.py:L1495–L1500](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/server/utils/diff_service.py#L1495-L1500)
+
+<!-- kb:knowledge owner=feature-workspace-git-diff facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**按文件流式获取与瞬态标记的选择**
+
+hunks 获取放弃一次聚合 `git diff`，改为按文件调用 `_run_git_diff_limited` 流式读取并在超过 `MAX_DIFF_SIZE_BYTES` 后停止累积 stdout（仍持续读空管道避免子进程阻塞）：以每文件一个 git 进程的成本，换取避免聚合 patch 的峰值内存，且前端详情层通常只请求选中路径。瞬态检测刻意使用 `rebase-merge`/`rebase-apply` 目录而非 `REBASE_HEAD`：代码注释说明后者在 rebase 成功收尾后被 Git 遗留，若作为信号会让 diff 永久返回 None（前端恒为 +0 -0）。
+
+Sources / 来源：[jiuwenswarm/server/utils/diff_service.py:L1495–L1537](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/server/utils/diff_service.py#L1495-L1537), [jiuwenswarm/server/utils/diff_service.py:L2157–L2175](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/server/utils/diff_service.py#L2157-L2175), [jiuwenswarm/server/utils/diff_service.py:L1569–L1602](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/server/utils/diff_service.py#L1569-L1602)
+
diff --git a/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-worktree.md b/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-worktree.md
index 7b8e921e..6f6053f4 100644
--- a/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-worktree.md
+++ b/knowledge/repos/jiuwenswarm/components/agent-server-runtime/feature-worktree.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/Harness.md
 feature: "worktree"
 entry_points: ["jiuwenswarm/server/runtime/agent_adapter/interface_code.py"]
-source_globs: ["jiuwenswarm/server/runtime/agent_adapter/interface_code.py", "jiuwenswarm/agents/harness/common/rails/*"]
+source_globs: ["jiuwenswarm/server/runtime/agent_adapter/interface_code.py", "jiuwenswarm/agents/harness/common/rails/*", "jiuwenswarm/channels/tui/frontend/src/core/event-handlers.ts"]
 ---
 
 # Worktree 隔离工作 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/_index.md b/knowledge/repos/jiuwenswarm/components/agents-team/_index.md
index 6f249cd0..7c9ea1f6 100644
--- a/knowledge/repos/jiuwenswarm/components/agents-team/_index.md
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/_index.md
@@ -68,3 +68,24 @@ sources: []
 - [JiuwenMemory 进程内 SDK 接入：实现深读](feature-depth-jiuwen-memory-sdk.md)
 - [图片生成与产物落盘：实现深读](feature-depth-image-generation.md)
 - [群聊数字分身与 owner 权限：实现深读](feature-depth-digital-avatar.md)
+- [Dynamic Memory CLI：SQLite UT 记忆库与发布/构建流水线](feature-dynamic-memory-cli.md)
+- [read_pdf：分页 PDF 文本读取工具（feature-pdf-reading-tool）](feature-pdf-reading-tool.md)
+- [DesignRail SDD 状态机（Spec-Driven Development）](feature-sdd-design-rail.md)
+- [SessionMessagingToolkit 跨会话消息六工具](feature-session-messaging-toolkit.md)
+- [user_todos Personal Per-Channel Todo Tool](feature-user-todos-tool.md)
+- [MCP Free/Paid Search Tools with Trusted-Search Provenance Lease](feature-web-search-tools.md)
+- [小艺手机工具 — 设备闹钟 CRUD（create/search/modify/delete_alarm）](feature-xiaoyi-alarm-crud.md)
+- [Xiaoyi 设备日历日程工具（create/search_calendar_event）](feature-xiaoyi-calendar-tools.md)
+- [小艺拨打电话工具 (call_phone)](feature-xiaoyi-call-phone-tool.md)
+- [小艺收藏工具（query/add/delete_collection）](feature-xiaoyi-collection-tools.md)
+- [search_contact 设备联系人搜索工具（feature-xiaoyi-contact-search）](feature-xiaoyi-contact-search.md)
+- [设备定位工具 get_user_location（feature-xiaoyi-location-tool）](feature-xiaoyi-location-tool.md)
+- [小艺备忘录工具（create_note / search_notes / modify_note）](feature-xiaoyi-note-tools.md)
+- [小艺图库工具：search_photo_gallery / upload_photo (photo_tools.py)](feature-xiaoyi-photo-gallery-tools.md)
+- [时间戳转北京时间工具 (convert_timestamp_to_utc8_time)](feature-xiaoyi-timestamp-utc8-tool.md)
+- [A2X Registry Client SDK — 同步/异步镜像式服务注册客户端](feature-a2x-registry-client-sdk.md)
+- [mcp_exec_command 跨平台命令执行工具](feature-command-execution-tool.md)
+- [LLM Wiki 知识库（wiki_ingest/query/lint 子代理）](feature-llm-wiki-knowledge-base.md)
+- [generate_video / check_video_status 提交后轮询的视频生成工具](feature-video-generation-tools.md)
+- [推送记录持久化与查询：pushdata_manager 与 view_push_result](feature-xiaoyi-pushdata-store-and-viewer.md)
+- [小艺保存到手机工具（save_media_to_gallery / save_file_to_file_manager）](feature-xiaoyi-save-to-phone-tools.md)
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-a2x-registry-client-sdk.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-a2x-registry-client-sdk.md
new file mode 100644
index 00000000..19f683d5
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-a2x-registry-client-sdk.md
@@ -0,0 +1,54 @@
+---
+title: "A2X Registry Client SDK — 同步/异步镜像式服务注册客户端"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/team/a2x/client/__init__.py:L1-L60, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/team/a2x/client/errors.py:L28-L73, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/team/a2x/client/transport.py:L36-L60, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/team/a2x/client/client.py:L38-L56, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/team/a2x/client/_internal.py:L23-L49, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/team/a2x/client/_internal.py:L229-L254, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/team/a2x/client/client.py:L99-L119, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/team/a2x/client/client.py:L123-L137, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/team/a2x/client/client.py:L232-L259, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/team/a2x/client/client.py:L415-L445, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/team/a2x/client/_internal.py:L26-L30, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/team/a2x/client/client.py:L388-L411, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/team/a2x/client/ownership.py:L1-L26, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/team/a2x/client/ownership.py:L146-L159, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:tests/unit_tests/agentserver/test_a2x_client_init.py:L243-L269, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:tests/unit_tests/agentserver/test_a2x_client_init.py:L273-L308, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:tests/unit_tests/agentserver/test_a2x_client_init.py:L348-L375]
+feature: "a2x-registry-client-sdk"
+entry_points: ["jiuwenswarm/agents/harness/team/a2x/client/__init__.py", "jiuwenswarm/agents/harness/team/a2x/client/async_client.py", "jiuwenswarm/agents/harness/team/a2x/client/client.py"]
+source_globs: ["jiuwenswarm/agents/harness/team/a2x/client/__init__.py", "jiuwenswarm/agents/harness/team/a2x/client/async_client.py", "jiuwenswarm/agents/harness/team/a2x/client/client.py", "jiuwenswarm/agents/harness/team/a2x/client/_internal.py", "jiuwenswarm/agents/harness/team/a2x/client/errors.py", "jiuwenswarm/agents/harness/team/a2x/client/models.py", "jiuwenswarm/agents/harness/team/a2x/client/transport.py", "jiuwenswarm/agents/harness/team/a2x/client/ownership.py"]
+---
+
+# A2X Registry Client SDK — 同步/异步镜像式服务注册客户端
+
+<!-- kb:knowledge owner=feature-a2x-registry-client-sdk facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**公共入口与生命周期**
+
+SDK 通过包的 `__init__` 导出两个镜像客户端：`A2XRegistryClient`（同步）与 `AsyncA2XRegistryClient`（异步），并重导出响应数据类（`RegisterResponse`、`PatchResponse`、`Reservation`、`AgentDetail` 等）和以 `A2XError` 为根的异常层级供 `except`/`isinstance` 使用，版本 `0.1.5`。两者均为上下文管理器：同步端 `close()`/`__exit__` 关闭传输层，异步端 `aclose()`/`__aexit__`；HTTP 错误统一映射为 `NotFoundError`（404）、`ValidationError`（400/422，含子类 `UserConfigServiceImmutableError`）、`ServerError`（5xx），网络故障映射为 `A2XConnectionError`；本地所有权检查失败抛 `NotOwnedError`（不发 HTTP 请求）。
+
+Sources / 来源：[jiuwenswarm/agents/harness/team/a2x/client/__init__.py:L1–L60](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/team/a2x/client/__init__.py#L1-L60), [jiuwenswarm/agents/harness/team/a2x/client/errors.py:L28–L73](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/team/a2x/client/errors.py#L28-L73), [jiuwenswarm/agents/harness/team/a2x/client/transport.py:L36–L60](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/team/a2x/client/transport.py#L36-L60)
+
+<!-- kb:knowledge owner=feature-a2x-registry-client-sdk facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**构造参数与常量默认值**
+
+两个客户端构造函数签名一致：`base_url`（默认 `http://127.0.0.1:8000`，经 `normalize_base_url` 补尾部 `/` 以支持挂载点）、`timeout`（默认 30.0 秒）、`api_key`（非空时生成 `Authorization: Bearer <key>` 头）、`ownership_file`（`None` → 默认 `~/.a2x_registry_client/owned.json`，`False` → 禁用持久化，`Path`/`str` → 原样使用）。其他默认值包括 `create_dataset` 的 `embedding_model="all-MiniLM-L6-v2"` 与 `formats={"a2a": "v0.0"}`（该常量与后端定义刻意重复，因客户端包独立发布不能导入项目其余部分），以及预约租约 `DEFAULT_RESERVATION_TTL=30` 秒。
+
+Sources / 来源：[jiuwenswarm/agents/harness/team/a2x/client/client.py:L38–L56](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/team/a2x/client/client.py#L38-L56), [jiuwenswarm/agents/harness/team/a2x/client/_internal.py:L23–L49](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/team/a2x/client/_internal.py#L23-L49), [jiuwenswarm/agents/harness/team/a2x/client/_internal.py:L229–L254](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/team/a2x/client/_internal.py#L229-L254)
+
+<!-- kb:knowledge owner=feature-a2x-registry-client-sdk facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**数据集、Agent 与空白代理池/预约能力**
+
+数据集操作只有创建与删除（`create_dataset` POST、`delete_dataset` DELETE），没有更新或列举入口。Agent 侧提供注册（POST `services/a2a`，`persistent=True` 时才记入本地所有权）、PUT 更新/`set_status`、带 AND 语义字段过滤的 `list_agents`、`get_agent`（非 JSON 载荷抛 `UnexpectedServiceTypeError`）与注销。在此之上构建团队代理流程：`register_blank_agent` 写入以 `description="__BLANK__"` 为发现哨兵、`status=online` 为可用门槛的空白卡片；`reserve_blank_agents` 以 `description=__BLANK__ AND status=online` 作为默认过滤集发起预约（调用方可通过 `extra_filters` 覆盖这两个键，包括 description/status 本身），返回作为上下文管理器的 `Reservation`。
+
+Sources / 来源：[jiuwenswarm/agents/harness/team/a2x/client/client.py:L99–L119](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/team/a2x/client/client.py#L99-L119), [jiuwenswarm/agents/harness/team/a2x/client/client.py:L123–L137](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/team/a2x/client/client.py#L123-L137), [jiuwenswarm/agents/harness/team/a2x/client/client.py:L232–L259](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/team/a2x/client/client.py#L232-L259), [jiuwenswarm/agents/harness/team/a2x/client/client.py:L415–L445](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/team/a2x/client/client.py#L415-L445)
+
+<!-- kb:knowledge owner=feature-a2x-registry-client-sdk facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**刻意重复的常量、易失的 L1 缓存与尽力而为的持久化**
+
+`DEFAULT_EMBEDDING_MODEL` 与后端定义刻意重复，因为客户端包独立发布、不能导入项目其余部分——代价是两处必须人工保持同步。`restore_to_blank` 的端点解析采用 L1 内存缓存 → L2 `get_agent` 读当前卡片 → L3 `ValueError` 的三级策略：缓存刻意不持久化，跨进程重启要靠 L2 的额外 GET 兜底。所有权持久化是尽力而为：`_save` 失败被降级为 warning（D8），理由是 HTTP 调用已成功、抛错会诱使调用方重试造成重复注册；所有权文件按 `base_url` 分段加跨平台文件锁、tmp+`os.replace` 原子重写，损坏文件按首跑友好处理为清空状态。
+
+Sources / 来源：[jiuwenswarm/agents/harness/team/a2x/client/_internal.py:L26–L30](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/team/a2x/client/_internal.py#L26-L30), [jiuwenswarm/agents/harness/team/a2x/client/client.py:L388–L411](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/team/a2x/client/client.py#L388-L411), [jiuwenswarm/agents/harness/team/a2x/client/ownership.py:L1–L26](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/team/a2x/client/ownership.py#L1-L26), [jiuwenswarm/agents/harness/team/a2x/client/ownership.py:L146–L159](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/team/a2x/client/ownership.py#L146-L159)
+
+<!-- kb:knowledge owner=feature-a2x-registry-client-sdk facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**基于假客户端替换的单测**
+
+`tests/unit_tests/agentserver/test_a2x_client_init.py` 通过 monkeypatch 把 `sys.modules` 中的客户端模块替换为内含 `_FakeAsyncA2XRegistryClient` 的假模块来测试上层适配器对 SDK 的调用方式：断言 teammate 启动时以 `{dataset, endpoint, service_id=None, persistent=True}` 调用 `register_blank_agent` 并关闭客户端，leader 预约路径以 `{dataset, n:1, ttl_seconds:30, holder_id:None, extra_filters:None}` 调用 `reserve_blank_agents` 并在释放后记录 holder。这些测试验证的是传参协议与调用时序，不经过真实 HTTP；destroy 路径还断言卡片替换传入完整空白卡片模板（`_BlankAgent_<endpoint>`/`__BLANK__`/`endpoint`/`online`）且 `release_lease=True`。
+
+Sources / 来源：[tests/unit_tests/agentserver/test_a2x_client_init.py:L243–L269](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/tests/unit_tests/agentserver/test_a2x_client_init.py#L243-L269), [tests/unit_tests/agentserver/test_a2x_client_init.py:L273–L308](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/tests/unit_tests/agentserver/test_a2x_client_init.py#L273-L308), [tests/unit_tests/agentserver/test_a2x_client_init.py:L348–L375](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/tests/unit_tests/agentserver/test_a2x_client_init.py#L348-L375)
+
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-auto-memory.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-auto-memory.md
index bdc5c59c..b17cd498 100644
--- a/knowledge/repos/jiuwenswarm/components/agents-team/feature-auto-memory.md
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-auto-memory.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/自动记忆.md
 feature: "auto-memory"
 entry_points: ["jiuwenswarm/agents/harness/common/auto_memory/extraction_runner.py"]
-source_globs: ["jiuwenswarm/agents/harness/common/auto_memory/extraction_runner.py", "jiuwenswarm/agents/harness/common/auto_memory/*"]
+source_globs: ["jiuwenswarm/agents/harness/common/auto_memory/extraction_runner.py", "jiuwenswarm/agents/harness/common/auto_memory/*", "jiuwenswarm/agents/harness/common/auto_memory/__init__.py", "jiuwenswarm/agents/harness/common/auto_memory/extract_memories.py", "jiuwenswarm/agents/harness/common/auto_memory/prompts.py", "jiuwenswarm/agents/harness/common/auto_memory/tool_restriction_rail.py"]
 ---
 
 # 对话后自动记忆 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-browser-tools.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-browser-tools.md
index 89ec183b..2d0fdbeb 100644
--- a/knowledge/repos/jiuwenswarm/components/agents-team/feature-browser-tools.md
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-browser-tools.md
@@ -11,7 +11,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/浏览器.md
 feature: "browser-tools"
 entry_points: ["jiuwenswarm/agents/swarm/browser_runtime.py", "jiuwenswarm/agents/harness/common/browser_config.py"]
-source_globs: ["jiuwenswarm/agents/swarm/browser_runtime.py", "jiuwenswarm/agents/harness/common/browser_config.py", "jiuwenswarm/agents/harness/common/*"]
+source_globs: ["jiuwenswarm/agents/swarm/browser_runtime.py", "jiuwenswarm/agents/harness/common/browser_config.py", "jiuwenswarm/agents/harness/common/*", "jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/navigate.py", "jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/browser/definition.ts", "jiuwenswarm/agents/harness/common/tools/browser_timeout_policy.py", "jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/ensure_browser.py", "jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/lib/cdp_client.py", "scripts/verify_playwright_mcp_offline.py", "jiuwenswarm/common/playwright_mcp_runtime.py", "scripts/update_playwright_mcp_runtime.py", "jiuwenswarm/agents/swarm/config_specs.py", "jiuwenswarm/agents/swarm/providers/code_subagents.py", "jiuwenswarm/server/runtime/agent_adapter/trusted_web_search.py", "jiuwenswarm/channels/web/frontend/src/features/browserAgentActivity.ts", "jiuwenswarm/agents/harness/common/tools/web_fetch_tools.py"]
 ---
 
 # 浏览器服务与网页工具 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-command-execution-tool.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-command-execution-tool.md
new file mode 100644
index 00000000..6c588bec
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-command-execution-tool.md
@@ -0,0 +1,30 @@
+---
+title: "mcp_exec_command 跨平台命令执行工具"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/command_tools.py:L1129-L1145, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/command_tools.py:L881-L885, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/command_tools.py:L990-L1020, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/command_tools.py:L83-L103, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/command_tools.py:L1221-L1223]
+feature: "command-execution-tool"
+entry_points: ["jiuwenswarm/agents/harness/common/tools/command_tools.py"]
+source_globs: ["jiuwenswarm/agents/harness/common/tools/command_tools.py", "jiuwenswarm/agents/harness/common/tools/command_execution_context.py", "jiuwenswarm/agents/harness/common/tools/command_runtime.py"]
+---
+
+# mcp_exec_command 跨平台命令执行工具
+
+<!-- kb:knowledge owner=feature-command-execution-tool facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**设置项与默认值**
+
+环境变量 `MCP_EXEC_COMMAND_MAX_TIMEOUT_SECONDS` 设定超时上限，未设置时默认 600（解析失败时取 3600），用户传入的 `timeout_seconds` 被夹到 `[1, max]`。非 Windows 上 `JW_START_NEW_SESSION`（默认 "true"，取值 `0/false/no/off` 之一则关闭）控制是否对子进程设置 `start_new_session=True`。沙箱路径下，启动器配置 `extra_params` 中 `fallback_on_failure` 为 True 或 `excluded_commands` 非空会被视为 host fallback 风险，命令被直接拒绝（fail-closed 错误），而非真正回退到宿主机执行。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/command_tools.py:L1129–L1145](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/command_tools.py#L1129-L1145), [jiuwenswarm/agents/harness/common/tools/command_tools.py:L881–L885](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/command_tools.py#L881-L885), [jiuwenswarm/agents/harness/common/tools/command_tools.py:L990–L1020](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/command_tools.py#L990-L1020)
+
+<!-- kb:knowledge owner=feature-command-execution-tool facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**测试支撑点**
+
+模块暴露 `reset_tui_spawn_history()`，docstring 标注用于测试，可清空 `_TUI_SPAWN_HISTORY` 来重置 TUI spawn 预算状态。TUI 预算的过期桶由 `_purge_stale_tui_spawn_buckets` 机会式清理（每窗口至多一次，删除全部条目均已过期的桶），防止会话字典无限增长。所示文件片段中没有出现其他测试入口。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/command_tools.py:L83–L103](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/command_tools.py#L83-L103), [jiuwenswarm/agents/harness/common/tools/command_tools.py:L1221–L1223](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/command_tools.py#L1221-L1223)
+
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-digital-avatar.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-digital-avatar.md
index 3b8ebdb7..f6f46645 100644
--- a/knowledge/repos/jiuwenswarm/components/agents-team/feature-digital-avatar.md
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-digital-avatar.md
@@ -12,7 +12,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/国内频道.md
 feature: "digital-avatar"
 entry_points: ["jiuwenswarm/agents/harness/common/rails/avatar_rail.py", "jiuwenswarm/agents/harness/common/rails/permissions/owner_scopes.py"]
-source_globs: ["jiuwenswarm/agents/harness/common/rails/avatar_rail.py", "jiuwenswarm/agents/harness/common/rails/permissions/owner_scopes.py"]
+source_globs: ["jiuwenswarm/agents/harness/common/rails/avatar_rail.py", "jiuwenswarm/agents/harness/common/rails/permissions/owner_scopes.py", "jiuwenswarm/gateway/channel_manager/im_platforms/feishu/feishu_connect.py", "jiuwenswarm/gateway/channel_manager/im_platforms/feishu/feishu_im_adapter.py", "jiuwenswarm/gateway/message_handler/message_handler.py", "jiuwenswarm/gateway/im_pipeline/im_inbound.py", "jiuwenswarm/gateway/im_pipeline/im_outbound.py", "jiuwenswarm/gateway/routing/interaction_context.py"]
 ---
 
 # 群聊数字分身与 owner 权限的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-distributed-team.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-distributed-team.md
index ea30caa1..28866aa9 100644
--- a/knowledge/repos/jiuwenswarm/components/agents-team/feature-distributed-team.md
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-distributed-team.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/分布式Team.md
 feature: "distributed-team"
 entry_points: ["jiuwenswarm/agents/harness/team/distributed_runtime.py"]
-source_globs: ["jiuwenswarm/agents/harness/team/distributed_runtime.py"]
+source_globs: ["jiuwenswarm/agents/harness/team/distributed_runtime.py", "jiuwenswarm/agents/harness/team/a2x/a2x_registry_runtime.py", "jiuwenswarm/agents/harness/team/team_manager.py", "jiuwenswarm/agents/harness/team/remote_member_bootstrap.py"]
 ---
 
 # 跨进程分布式 Team 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-dynamic-memory-cli.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-dynamic-memory-cli.md
new file mode 100644
index 00000000..5e5cd2f1
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-dynamic-memory-cli.md
@@ -0,0 +1,54 @@
+---
+title: "Dynamic Memory CLI：SQLite UT 记忆库与发布/构建流水线"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py:L405-L424, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py:L380-L402, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py:L469-L486, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py:L506-L539, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py:L578-L582, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/rails/eternal_conversation/memory_cli.py:L55-L69, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py:L59-L95, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py:L286-L318, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/rails/eternal_conversation/memory_cli.py:L89-L107, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py:L506-L545, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py:L86-L95, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py:L311-L315, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py:L218-L244, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py:L321-L339, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py:L342-L402]
+feature: "dynamic-memory-cli"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py", "jiuwenswarm/agents/harness/common/rails/eternal_conversation/memory_cli.py"]
+---
+
+# Dynamic Memory CLI：SQLite UT 记忆库与发布/构建流水线
+
+<!-- kb:knowledge owner=feature-dynamic-memory-cli facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**内置验证入口**
+
+`test` 命令（run_tests）对每个 active UT 的每条 query 跑一次 search_one，断言自身出现在 matches 且 must_include 短语存在于命中内容，返回 total/failed/failures；`--built-only` 限定已构建 UT。build_pending 在同一事务内做等价验收，任何失败整体回滚并返回 status=failed；`bench` 命令测量全量 query 的 p95/mean 检索耗时。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py:L405–L424](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py#L405-L424), [jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py:L380–L402](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py#L380-L402), [jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py:L469–L486](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py#L469-L486)
+
+<!-- kb:knowledge owner=feature-dynamic-memory-cli facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**命令行入口与输出契约**
+
+入口是 `main(argv)`，argparse 定义子命令 init/search/list/show/check-conflicts/add/update/retire/get-state/publish-pending/freeze-pending/build-pending/test/bench。命令执行结果通过 `emit_json` 以单个 JSON 文档写到 stdout；try 块内抛出的异常会被捕获，输出 `{"error": 类型名, "message": ...}` 并以退出码 1 结束。注意 argparse 解析发生在 try 之前（L539），参数错误或 --help 不走该 JSON 错误路径。`DynamicMemoryGateway.call(*args)` 是进程外的异步封装，向同一脚本转发子命令。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py:L506–L539](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py#L506-L539), [jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py:L578–L582](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py#L578-L582), [jiuwenswarm/agents/harness/common/rails/eternal_conversation/memory_cli.py:L55–L69](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/rails/eternal_conversation/memory_cli.py#L55-L69)
+
+<!-- kb:knowledge owner=feature-dynamic-memory-cli facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**SQLite 状态机与子进程网关**
+
+存储是单文件 `memory.sqlite3`（WAL、foreign_keys=ON），含 uts、built_docs（外键级联到 uts.id）和 meta 三张表；meta 保存 schema_version、memory_revision、snapshot_revision、covered_through 和 snapshot。发布路径 publish-pending 在 BEGIN IMMEDIATE 事务中校验提案的 base 修订号、游标连续性，然后应用 changed_uts 并推进修订号；上层 `DynamicMemoryGateway` 始终以子进程方式调用该脚本（调用方不直接碰数据库），完成的调用会把参数、耗时与结果写入 evidence 审计流——注意子进程创建失败或任务被取消时不会到达该审计写入。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py:L59–L95](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py#L59-L95), [jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py:L286–L318](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py#L286-L318), [jiuwenswarm/agents/harness/common/rails/eternal_conversation/memory_cli.py:L89–L107](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/rails/eternal_conversation/memory_cli.py#L89-L107)
+
+<!-- kb:knowledge owner=feature-dynamic-memory-cli facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**可配置项：--root、init --path 与 meta 默认值**
+
+全局 `--root` 决定项目根目录，但 `init` 例外：它使用必需的 `--path` 参数；其余命令先用 require_project 校验 memory.sqlite3 存在。init 写入 meta 默认值：schema_version=1、memory_revision=0、snapshot_revision=0、covered_through=0、空 snapshot。发布成功时 snapshot_revision 总是 +1、covered_through 更新为 to_cursor、snapshot 被覆盖，而 memory_revision 仅在 changed_uts 非空时 +1。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py:L506–L545](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py#L506-L545), [jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py:L86–L95](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py#L86-L95), [jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py:L311–L315](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py#L311-L315)
+
+<!-- kb:knowledge owner=feature-dynamic-memory-cli facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**检索与发布/构建流水线**
+
+search 对 active UT 检索：pending UT 用内容/queries/must_include/tags/source 拼接的临时文档打分，built UT 则读取 built_docs 文档并要求其 content_hash 与当前 UT 一致且状态合格，否则跳过；结果按 priority、score、id 排序。发布/构建流水线是 publish-pending → freeze-pending（把 pending UT 原子写入冻结批次文件，字段名用 frozen_at 以避免与 UT.updated_at 的时序歧义）→ build-pending（同一事务内重建文档并做检索验收，任一失败整体回滚）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py:L218–L244](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py#L218-L244), [jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py:L321–L339](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py#L321-L339), [jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py:L342–L402](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/dynamic-memory-cli/scripts/dynamic_memory_cli.py#L342-L402)
+
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-human-team.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-human-team.md
index a9bea544..8e07033c 100644
--- a/knowledge/repos/jiuwenswarm/components/agents-team/feature-human-team.md
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-human-team.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/AgentTeam人类成员联机协作.md
 feature: "human-team"
 entry_points: ["jiuwenswarm/agents/harness/team/team_manager.py"]
-source_globs: ["jiuwenswarm/agents/harness/team/team_manager.py", "jiuwenswarm/agents/harness/team/*"]
+source_globs: ["jiuwenswarm/agents/harness/team/team_manager.py", "jiuwenswarm/agents/harness/team/*", "jiuwenswarm/gateway/routing/session_sharing.py", "jiuwenswarm/server/runtime/agent_adapter/team_helpers.py", "jiuwenswarm/gateway/message_handler/join_exit_handlers.py", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/index.tsx"]
 ---
 
 # 人类团队成员与人工协作 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-image-generation.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-image-generation.md
index 710f40c0..90a22281 100644
--- a/knowledge/repos/jiuwenswarm/components/agents-team/feature-image-generation.md
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-image-generation.md
@@ -11,7 +11,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/配置信息.md
 feature: "image-generation"
 entry_points: ["jiuwenswarm/agents/harness/common/tools/image_tools.py", "jiuwenswarm/agents/harness/common/tools/multimodal_config.py"]
-source_globs: ["jiuwenswarm/agents/harness/common/tools/image_tools.py", "jiuwenswarm/agents/harness/common/tools/multimodal_config.py"]
+source_globs: ["jiuwenswarm/agents/harness/common/tools/image_tools.py", "jiuwenswarm/agents/harness/common/tools/multimodal_config.py", "jiuwenswarm/resources/agent/workspace/skills/baoyu-image-gen/scripts/build-batch.ts", "jiuwenswarm/resources/agent/workspace/skills/baoyu-image-gen/scripts/providers/agnes.ts", "jiuwenswarm/resources/agent/workspace/skills/baoyu-image-gen/scripts/providers/azure.ts", "jiuwenswarm/resources/agent/workspace/skills/baoyu-image-gen/scripts/main.ts", "jiuwenswarm/resources/agent/workspace/skills/baoyu-image-gen/scripts/providers/codex-cli.ts", "jiuwenswarm/resources/agent/workspace/skills/baoyu-image-gen/scripts/providers/dashscope.ts", "jiuwenswarm/resources/agent/workspace/skills/baoyu-image-gen/scripts/providers/google.ts", "jiuwenswarm/resources/agent/workspace/skills/baoyu-image-gen/scripts/providers/jimeng.ts", "jiuwenswarm/resources/agent/workspace/skills/baoyu-image-gen/scripts/providers/minimax.ts", "jiuwenswarm/resources/agent/workspace/skills/baoyu-image-gen/scripts/codex-imagegen/cache.ts", "jiuwenswarm/resources/agent/workspace/skills/baoyu-image-gen/scripts/codex-imagegen/main.ts", "jiuwenswarm/resources/agent/workspace/skills/baoyu-image-gen/scripts/codex-imagegen/types.ts", "jiuwenswarm/resources/agent/workspace/skills/baoyu-image-gen/scripts/types.ts", "jiuwenswarm/resources/agent/workspace/skills/baoyu-image-gen/scripts/providers/openrouter.ts", "jiuwenswarm/resources/agent/workspace/skills/baoyu-image-gen/scripts/providers/replicate.ts", "jiuwenswarm/resources/agent/workspace/skills/baoyu-image-gen/scripts/providers/seedream.ts", "jiuwenswarm/resources/agent/workspace/skills/baoyu-image-gen/scripts/providers/zai.ts"]
 ---
 
 # 图片生成与产物落盘的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-llm-wiki-knowledge-base.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-llm-wiki-knowledge-base.md
new file mode 100644
index 00000000..f2024993
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-llm-wiki-knowledge-base.md
@@ -0,0 +1,38 @@
+---
+title: "LLM Wiki 知识库（wiki_ingest/query/lint 子代理）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/wiki_tools.py:L195-L233, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/wiki_tools.py:L242-L258, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/wiki_tools.py:L318-L347, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/wiki_tools.py:L368-L415, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/wiki_tools.py:L470-L485, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:tests/unit_tests/agents/test_wiki_tools_runtime_config.py:L30-L74, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:tests/unit_tests/agents/test_wiki_tools_runtime_config.py:L77-L94, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:tests/unit_tests/agents/test_wiki_tools_runtime_config.py:L97-L125]
+feature: "llm-wiki-knowledge-base"
+entry_points: ["jiuwenswarm/agents/harness/common/tools/wiki_tools.py"]
+source_globs: ["jiuwenswarm/agents/harness/common/tools/wiki_tools.py"]
+---
+
+# LLM Wiki 知识库（wiki_ingest/query/lint 子代理）
+
+<!-- kb:knowledge owner=feature-llm-wiki-knowledge-base facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**LLMWiki 包装 DeepAgent 的分层结构**
+
+LLMWiki 是核心类：构造时把 workspace 划分为 sources/、wiki/、schema/ 三个目录（L195-201），并通过 create_deep_agent 创建一个内部 DeepAgent（L216-233）；ingest/query/lint 都是把自然语言指令拼成 query 后调用 self.agent.invoke，共享同一个 Session（L340、L354、L365）。ensure_initialized 幂等地创建目录并写入 schema/AGENT.md、wiki/index.md、wiki/log.md 的初始内容（L242-308）。ingest 按 SHA-256 去重（force=False 且已记录则跳过），仅当结果不含 "error" 且 output 不以 "[ERROR" 开头时才把哈希写入 manifest——即代码只保证显式失败时不新增记录，不保证失败后可重试（L318-346）。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/wiki_tools.py:L195–L233](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/wiki_tools.py#L195-L233), [jiuwenswarm/agents/harness/common/tools/wiki_tools.py:L242–L258](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/wiki_tools.py#L242-L258), [jiuwenswarm/agents/harness/common/tools/wiki_tools.py:L318–L347](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/wiki_tools.py#L318-L347)
+
+<!-- kb:knowledge owner=feature-llm-wiki-knowledge-base facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**workspace 解析与模型来源**
+
+workspace 由 _resolve_workspace 规范化：空串或等于 DEFAULT_WIKI_DIR 时映射到 base_dir/DEFAULT_WIKI_DIR；相对路径挂在 get_agent_workspace_dir() 之下；若路径末段不是 DEFAULT_WIKI_DIR 则追加该目录名（L398-415）。三个工具入口的模型固定来自 _get_default_model()（L478、L537、L570），该函数从默认模型配置取值并补齐 api_key/api_base/client_provider/model_name 等缺省以防 ValidationError（L368-395）；而 LLMWiki 类本身接受调用方传入的 model 并直接使用（L176、L217）。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/wiki_tools.py:L368–L415](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/wiki_tools.py#L368-L415), [jiuwenswarm/agents/harness/common/tools/wiki_tools.py:L470–L485](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/wiki_tools.py#L470-L485)
+
+<!-- kb:knowledge owner=feature-llm-wiki-knowledge-base facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**现有单测覆盖 _create_llm_wiki 与会话 lineage**
+
+tests/unit_tests/agents/test_wiki_tools_runtime_config.py 有三个用例：test_create_llm_wiki_propagates_runtime_policy_and_parent_lineage 通过 monkeypatch 假配置与会话，断言 enable_read_image_multimodal=False 被透传、session_id 形如 "{owner}:subagent:wiki:{workspace_scope}" 且 parent_session_id 指向父会话，并断言亲和配置的 enable_kv_cache_affinity 为 True（L30-74）；test_llm_wiki_session_exposes_provider_cache_lineage 构造真实 LLMWiki（stub 掉 create_deep_agent）后调用 resolve_session_lineage 验证内部 Session 的 lineage 解析结果（L77-94）；第三个用例验证 OpenAI affinity 模型同样得到启用亲和的 kv_cache_affinity_config（L97-125）。这些测试断言的是配置构造与 lineage，不涉及 ingest/query/lint 的运行时行为。
+
+Sources / 来源：[tests/unit_tests/agents/test_wiki_tools_runtime_config.py:L30–L74](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/tests/unit_tests/agents/test_wiki_tools_runtime_config.py#L30-L74), [tests/unit_tests/agents/test_wiki_tools_runtime_config.py:L77–L94](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/tests/unit_tests/agents/test_wiki_tools_runtime_config.py#L77-L94), [tests/unit_tests/agents/test_wiki_tools_runtime_config.py:L97–L125](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/tests/unit_tests/agents/test_wiki_tools_runtime_config.py#L97-L125)
+
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-memory.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-memory.md
index 69c5be66..9540dcda 100644
--- a/knowledge/repos/jiuwenswarm/components/agents-team/feature-memory.md
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-memory.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/记忆.md
 feature: "memory"
 entry_points: ["jiuwenswarm/agents/harness/common/memory/manager.py"]
-source_globs: ["jiuwenswarm/agents/harness/common/memory/manager.py", "jiuwenswarm/agents/harness/common/memory/*"]
+source_globs: ["jiuwenswarm/agents/harness/common/memory/manager.py", "jiuwenswarm/agents/harness/common/memory/*", "jiuwenswarm/server/runtime/agent_adapter/interface.py", "jiuwenswarm/server/runtime/agent_adapter/interface_deep.py", "jiuwenswarm/agents/harness/common/memory/dreaming/__init__.py", "jiuwenswarm/agents/harness/common/memory/dreaming/sweeper.py", "jiuwenswarm/agents/harness/common/memory/external_memory_config.py", "jiuwenswarm/agents/harness/common/memory/external_memory_builder.py", "jiuwenswarm/agents/harness/common/memory/forbidden.py", "jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/collectors/memory_collector.py", "jiuwenswarm/agents/harness/common/memory/embeddings.py", "jiuwenswarm/agents/harness/common/tools/memory_tools.py", "jiuwenswarm/common/config.py", "jiuwenswarm/agents/harness/common/rails/memory_forbidden_rail.py", "jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py", "jiuwenswarm/agents/harness/common/memory/internal.py", "jiuwenswarm/agents/harness/common/memory/config.py", "jiuwenswarm/agents/harness/common/memory/__init__.py", "jiuwenswarm/agents/harness/common/memory/types.py", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/memory.ts", "jiuwenswarm/channels/tui/frontend/src/ui/app-screen.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/memory-path-utils.ts", "jiuwenswarm/channels/tui/frontend/src/app-state.ts"]
 ---
 
 # 长期记忆 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-multimodal.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-multimodal.md
index 042b6dfa..034929e9 100644
--- a/knowledge/repos/jiuwenswarm/components/agents-team/feature-multimodal.md
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-multimodal.md
@@ -11,7 +11,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/Harness.md
 feature: "multimodal"
 entry_points: ["jiuwenswarm/agents/harness/common/tools/multimodal_config.py", "jiuwenswarm/agents/harness/common/tools/image_tools.py"]
-source_globs: ["jiuwenswarm/agents/harness/common/tools/multimodal_config.py", "jiuwenswarm/agents/harness/common/tools/image_tools.py", "jiuwenswarm/agents/harness/common/tools/*"]
+source_globs: ["jiuwenswarm/agents/harness/common/tools/multimodal_config.py", "jiuwenswarm/agents/harness/common/tools/image_tools.py", "jiuwenswarm/agents/harness/common/tools/*", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/agent/AgentSettings.css", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/agent/AgentSettings.tsx", "jiuwenswarm/agents/harness/common/tools/audio_tools.py", "jiuwenswarm/server/runtime/image_modality_warmup.py", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/agent/mediaCapabilities.ts", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/agent/mediaModelConfig.ts", "jiuwenswarm/common/media_capability_config.py", "jiuwenswarm/agents/harness/common/rails/multimodal_image_rail.py", "jiuwenswarm/agents/harness/common/prompt/user_prompt_builder.py", "jiuwenswarm/server/runtime/agent_adapter/interface_deep.py", "jiuwenswarm/agents/swarm/providers/tools.py", "jiuwenswarm/agents/harness/common/tools/video_tools.py", "jiuwenswarm/agents/harness/common/tools/visual_gen_tools.py", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/InputArea.tsx", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/agent/MediaModelConfigDialog.tsx", "jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/image_reading_tool.py"]
 ---
 
 # 多模态理解与媒体配置 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-pdf-reading-tool.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-pdf-reading-tool.md
new file mode 100644
index 00000000..74b08446
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-pdf-reading-tool.md
@@ -0,0 +1,58 @@
+---
+title: "read_pdf：分页 PDF 文本读取工具（feature-pdf-reading-tool）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/pdf_tools.py:L170-L183, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/pdf_tools.py:L213-L218, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/pdf_tools.py:L244-L254, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/pdf_tools.py:L1-L10, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/pdf_tools.py:L239-L262, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/pdf_tools.py:L36-L41, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/pdf_tools.py:L273-L275, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/pdf_tools.py:L143-L168, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/pdf_tools.py:L185-L211, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/pdf_tools.py:L125-L130, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/pdf_tools.py:L112-L130, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/pdf_tools.py:L257-L275, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:tests/unit_tests/agents/test_pdf_tools.py:L324-L335]
+feature: "pdf-reading-tool"
+entry_points: ["jiuwenswarm/agents/harness/common/tools/pdf_tools.py"]
+source_globs: ["jiuwenswarm/agents/harness/common/tools/pdf_tools.py"]
+---
+
+# read_pdf：分页 PDF 文本读取工具（feature-pdf-reading-tool）
+
+<!-- kb:knowledge owner=feature-pdf-reading-tool facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的行为**
+
+支持增量分页读取：超出的请求页会被记为 out-of-range 跳过，未读页、截断和空文本页都以明确的文本披露回传，提示模型再次调用或改用视觉工具。扫描页（无文本层）输出 `[no text layer on this page]` 并在结尾汇总，建议用 image/vision 工具兜底。工具描述（模型可见文档）通过 f-string 引用常量，使上限与默认值改变时描述自动同步。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/pdf_tools.py:L170–L183](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/pdf_tools.py#L170-L183), [jiuwenswarm/agents/harness/common/tools/pdf_tools.py:L213–L218](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/pdf_tools.py#L213-L218), [jiuwenswarm/agents/harness/common/tools/pdf_tools.py:L244–L254](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/pdf_tools.py#L244-L254)
+
+<!-- kb:knowledge owner=feature-pdf-reading-tool facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证入口**
+
+Inference / 设计推断（非作者历史意图）：
+
+本次固定版本展示的输入只有 pdf_tools.py 源文件本身，未附带任何测试文件或文档；该文件内没有内嵌的自测逻辑。无法从所示证据确认此工具的测试覆盖情况，validation  facet 以所示范围为限，不作存在性断言。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/pdf_tools.py:L1–L10](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/pdf_tools.py#L1-L10)
+
+<!-- kb:knowledge owner=feature-pdf-reading-tool facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**入口与调用契约**
+
+公开入口是经 `@tool` 注册的异步函数 `read_pdf(pdf_path, pages=None, max_chars=50_000)`；`pages` 接受整数、列表或形如 `"1-5"`/`"1,3,8-10"` 的字符串，省略或为空表示读全部页，但实际读取仍受每次调用最多 100 页（`_MAX_PAGES_PER_CALL`）与 `max_chars` 字符截断约束。返回值为拼接的 Markdown 式文本；任何被 `except Exception` 捕获的异常都被转换为 `[ERROR]: read_pdf failed: ...` 字符串而非抛出。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/pdf_tools.py:L239–L262](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/pdf_tools.py#L239-L262), [jiuwenswarm/agents/harness/common/tools/pdf_tools.py:L36–L41](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/pdf_tools.py#L36-L41), [jiuwenswarm/agents/harness/common/tools/pdf_tools.py:L273–L275](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/pdf_tools.py#L273-L275)
+
+<!-- kb:knowledge owner=feature-pdf-reading-tool facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**受限读取与主动披露的取舍**
+
+Inference / 设计推断（非作者历史意图）：
+
+读取量被页数上限（100 页/次，超出的选中页直接截断）和 `max_chars` 双重限制以保护上下文窗口，代价是模型必须多轮续读。两类遗漏的披露位置不同：因 `pages` 只选子集或页数上限截断而未读的页，在返回头部的 `[Partial read: ...]` 中列出并给出补救指引（总页数不超上限时建议省略 `pages`，否则提示从首个未读页续读）；而 `max_chars` 触发的截断在循环内追加尾部说明、列出未读页并建议调大 `max_chars`，且截断后即终止循环。路径校验先于 pdfplumber 导入，使依赖缺失环境下路径错误也能清晰呈现。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/pdf_tools.py:L143–L168](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/pdf_tools.py#L143-L168), [jiuwenswarm/agents/harness/common/tools/pdf_tools.py:L185–L211](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/pdf_tools.py#L185-L211), [jiuwenswarm/agents/harness/common/tools/pdf_tools.py:L125–L130](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/pdf_tools.py#L125-L130)
+
+<!-- kb:knowledge owner=feature-pdf-reading-tool facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**read_pdf 的分层结构与执行流**
+
+工具由三层组成：异步入口 `read_pdf` 先经 `_normalize_request` 把原始入参规整为 frozen dataclass `ReadPdfRequest`，再把同步的 `_read_pdf_sync`（pdfplumber 提取）通过 `asyncio.to_thread` 卸载到线程，避免阻塞事件循环。`_resolve_pdf_path` 负责路径边界：相对路径锚定在 Core 的当前主工作区（`get_workspace()`，获取不到则报错），并强制存在、是文件且后缀为 .pdf；路径校验先于 `import pdfplumber`，使依赖缺失环境下路径错误也能先呈现。运行中 Exception 被捕获并转为 `[ERROR]: read_pdf failed: ...` 字符串返回；缺失 `pdf_path` 时的 ValidationError 则按测试预期从 `read_pdf.invoke` 传播出去，不转为字符串。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/pdf_tools.py:L112–L130](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/pdf_tools.py#L112-L130), [jiuwenswarm/agents/harness/common/tools/pdf_tools.py:L257–L275](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/pdf_tools.py#L257-L275), [tests/unit_tests/agents/test_pdf_tools.py:L324–L335](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/tests/unit_tests/agents/test_pdf_tools.py#L324-L335)
+
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-planning.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-planning.md
index 54f90b64..3c6df6ea 100644
--- a/knowledge/repos/jiuwenswarm/components/agents-team/feature-planning.md
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-planning.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/任务规划.md
 feature: "planning"
 entry_points: ["jiuwenswarm/agents/harness/code/rails/code_task_planning_rail.py"]
-source_globs: ["jiuwenswarm/agents/harness/code/rails/code_task_planning_rail.py", "jiuwenswarm/agents/harness/common/*"]
+source_globs: ["jiuwenswarm/agents/harness/code/rails/code_task_planning_rail.py", "jiuwenswarm/agents/harness/common/*", "jiuwenswarm/agents/harness/code/prompt/code_todo_tool_prompts.py", "jiuwenswarm/agents/harness/code/tools/__init__.py", "jiuwenswarm/agents/harness/code/tools/code_todo_tools.py", "jiuwenswarm/channels/web/frontend/src/components/MemberTaskDrawer/index.tsx", "jiuwenswarm/server/runtime/agent_adapter/interface_deep.py", "jiuwenswarm/channels/web/frontend/src/components/TodoList/TodoItem.tsx", "jiuwenswarm/channels/web/frontend/src/components/TodoList/index.tsx", "jiuwenswarm/channels/web/frontend/src/components/teamArea/CompactTaskList.tsx", "jiuwenswarm/channels/web/frontend/src/components/teamArea/MemberTaskList.tsx", "jiuwenswarm/channels/web/frontend/src/components/teamArea/TaskPlanningPanel.tsx", "jiuwenswarm/channels/web/frontend/src/components/teamArea/TeamMembersPanel.tsx", "jiuwenswarm/channels/web/frontend/src/components/teamArea/UnassignedTeamAvatar.tsx", "jiuwenswarm/channels/web/frontend/src/components/TeamTaskEvents.tsx", "jiuwenswarm/channels/web/frontend/src/components/teamArea/taskProgress.ts", "jiuwenswarm/channels/web/frontend/src/components/AgentPanel/FileViewer.tsx", "jiuwenswarm/channels/web/frontend/src/types/todo.ts", "jiuwenswarm/agents/harness/common/tools/todo_toolkits.py", "jiuwenswarm/agents/harness/common/tools/todo_compat.py", "jiuwenswarm/channels/tui/frontend/src/ui/components/todo-list.ts", "jiuwenswarm/channels/tui/frontend/src/app-state.ts", "jiuwenswarm/channels/web/frontend/src/components/teamArea/index.tsx", "jiuwenswarm/channels/web/frontend/src/stores/todoStore.ts"]
 ---
 
 # 任务规划与 Todo 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-sdd-design-rail.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-sdd-design-rail.md
new file mode 100644
index 00000000..71609cc7
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-sdd-design-rail.md
@@ -0,0 +1,56 @@
+---
+title: "DesignRail SDD 状态机（Spec-Driven Development）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/code/rails/sdd/design_rail/rail.py:L2-L17, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/code/rails/sdd/common/rail_state_machine.py:L101-L137, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/code/rails/sdd/common/rail_state_machine.py:L255-L301, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/code/rails/sdd/design_rail/__init__.py:L4-L12, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/code/rails/sdd/common/rail_state_machine.py:L297-L333, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/code/rails/sdd/design_rail/rail.py:L36-L53, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/code/rails/sdd/design_rail/skills/aet-req-analysis/scripts/assemble-template.mjs:L14-L20, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/code/rails/sdd/design_rail/rail.py:L48-L53, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/code/rails/sdd/design_rail/rail.py:L141-L149, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/code/rails/sdd/common/rail_state_machine.py:L8-L13, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/code/rails/sdd/design_rail/config_loader.py:L58-L72, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/code/rails/sdd/common/rail_state_machine.py:L255-L264, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/code/rails/sdd/common/rail_state_machine.py:L343-L365, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/code/rails/sdd/design_rail/rail.py:L70-L92, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/code/rails/sdd/design_rail/rail.py:L97-L149]
+feature: "sdd-design-rail"
+entry_points: ["jiuwenswarm/agents/harness/code/rails/sdd/common/rail_state_machine.py", "jiuwenswarm/agents/harness/code/rails/sdd/design_rail/__init__.py", "jiuwenswarm/agents/harness/code/rails/sdd/design_rail/rail.py"]
+source_globs: ["jiuwenswarm/agents/harness/code/rails/sdd/common/rail_state_machine.py", "jiuwenswarm/agents/harness/code/rails/sdd/design_rail/__init__.py", "jiuwenswarm/agents/harness/code/rails/sdd/design_rail/rail.py", "jiuwenswarm/agents/harness/code/rails/sdd/design_rail/skills/aet-req-analysis/scripts/assemble-checklist.mjs", "jiuwenswarm/agents/harness/code/rails/sdd/design_rail/skills/aet-req-analysis/scripts/assemble-template.mjs", "jiuwenswarm/agents/harness/code/rails/sdd/design_rail/skills/aet-req-design/scripts/assemble-checklist.mjs", "jiuwenswarm/agents/harness/code/rails/sdd/design_rail/skills/aet-req-design/scripts/assemble-template.mjs", "jiuwenswarm/agents/harness/code/rails/sdd/design_rail/config_loader.py", "jiuwenswarm/agents/harness/code/rails/sdd/__init__.py", "jiuwenswarm/agents/harness/code/rails/sdd/common/__init__.py"]
+---
+
+# DesignRail SDD 状态机（Spec-Driven Development）
+
+<!-- kb:knowledge owner=feature-sdd-design-rail facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**职责分层与控制流**
+
+DesignRail 只贡献 SDD 特有部分：6 阶段流（init→analysis→analysis_review→design→design_review→done，来自 config.yaml）、skills/ 下的方法论、以及 ask_user 评审处理；状态存取、sdd_advance 注册、方法论注入、产物门禁、feature 名解析全部由 RailStateMachineBase 提供。控制流是回调环：before_model_call 每次模型调用前先移除旧 prompt 段再注入当前阶段的 SKILL.md 方法论（无 skill 的阶段注入 bootstrap，done 不注入）；LLM 调用 sdd_advance 触发 _handle_advance 校验 next 边与产物存在性后迁移 `self._stage`（纯内存态），下一轮 before_model_call 注入新阶段方法论。
+
+Sources / 来源：[jiuwenswarm/agents/harness/code/rails/sdd/design_rail/rail.py:L2–L17](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/code/rails/sdd/design_rail/rail.py#L2-L17), [jiuwenswarm/agents/harness/code/rails/sdd/common/rail_state_machine.py:L101–L137](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/code/rails/sdd/common/rail_state_machine.py#L101-L137), [jiuwenswarm/agents/harness/code/rails/sdd/common/rail_state_machine.py:L255–L301](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/code/rails/sdd/common/rail_state_machine.py#L255-L301)
+
+<!-- kb:knowledge owner=feature-sdd-design-rail facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的行为与依赖**
+
+已实现的行为包括：产物门禁（前进前当前阶段声明的 artifacts 必须存在于 `.aet/features/<feature>/design/`，feature 取最新修改的 `.aet/features/` 子目录）；从 done 重置开启新流程（可选 feature_name，先做路径安全校验再建目录）；评审 reject 关键词启发式（中英词表 + ASCII 词边界正则，避免 "project" 误匹配 "reject"）。挂载条件是 code mode 且 `modes.code.sdd.enabled=true`，由 `JiuwenSwarmCodeAdapter._build_design_rail` 构建。技能包内含 Node 脚本 assemble-template.mjs / assemble-checklist.mjs，按 项目custom→项目aet→用户custom→用户aet→内置 五级搜索序组装模板，占位符 `{{component,level}}` 展开并自动编号章节。
+
+Sources / 来源：[jiuwenswarm/agents/harness/code/rails/sdd/design_rail/__init__.py:L4–L12](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/code/rails/sdd/design_rail/__init__.py#L4-L12), [jiuwenswarm/agents/harness/code/rails/sdd/common/rail_state_machine.py:L297–L333](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/code/rails/sdd/common/rail_state_machine.py#L297-L333), [jiuwenswarm/agents/harness/code/rails/sdd/design_rail/rail.py:L36–L53](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/code/rails/sdd/design_rail/rail.py#L36-L53), [jiuwenswarm/agents/harness/code/rails/sdd/design_rail/skills/aet-req-analysis/scripts/assemble-template.mjs:L14–L20](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/code/rails/sdd/design_rail/skills/aet-req-analysis/scripts/assemble-template.mjs#L14-L20)
+
+<!-- kb:knowledge owner=feature-sdd-design-rail facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**设计取舍**
+
+Inference / 设计推断（非作者历史意图）：
+
+返工边不放进声明式配置：config.yaml 的 `stages.<name>.next` 只列前进边，返工映射硬编码在 `_REWORK_TARGETS`，代码注释明确要求新增 *_review 阶段时必须同步更新该映射——配置简洁但引入了隐式耦合（inference 依据注释）。approve 分支不自动迁移是防双推进：after_tool_call 迁移后 Agent 再调 sdd_advance 会因已在下一阶段而报 "not a valid next"，故依赖 SKILL.md 的 R4 步骤让 Agent 显式调用（代码注释给出该理由）。状态纯内存、无持久化（基类 docstring 声明），换取简单但会话内有效。
+
+Sources / 来源：[jiuwenswarm/agents/harness/code/rails/sdd/design_rail/rail.py:L48–L53](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/code/rails/sdd/design_rail/rail.py#L48-L53), [jiuwenswarm/agents/harness/code/rails/sdd/design_rail/rail.py:L141–L149](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/code/rails/sdd/design_rail/rail.py#L141-L149), [jiuwenswarm/agents/harness/code/rails/sdd/common/rail_state_machine.py:L8–L13](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/code/rails/sdd/common/rail_state_machine.py#L8-L13)
+
+<!-- kb:knowledge owner=feature-sdd-design-rail facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证机制**
+
+本批输入未展示任何 pytest 测试文件，可证实的验证机制是运行时校验：config_loader.validate 聚合全部错误（不短路上报）返回 ValidationResult，DesignRail 构造失败即阻止挂载（BC-005：拒绝挂载并回退普通 Code 模式）；_handle_advance 对非法 stage、非法 next、缺失产物分别返回 `{"ok": false, "error": ...}` 字典而非抛异常（注释声明永不崩溃工具调用）；_transition_to 校验目标在 stages 中防止状态机卡死。测试入口的覆盖情况在所示证据中无法确认。
+
+Sources / 来源：[jiuwenswarm/agents/harness/code/rails/sdd/design_rail/config_loader.py:L58–L72](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/code/rails/sdd/design_rail/config_loader.py#L58-L72), [jiuwenswarm/agents/harness/code/rails/sdd/common/rail_state_machine.py:L255–L264](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/code/rails/sdd/common/rail_state_machine.py#L255-L264), [jiuwenswarm/agents/harness/code/rails/sdd/common/rail_state_machine.py:L343–L365](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/code/rails/sdd/common/rail_state_machine.py#L343-L365)
+
+<!-- kb:knowledge owner=feature-sdd-design-rail facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**公开入口与生命周期**
+
+DesignRail 的公开入口是关键字专属构造器 `DesignRail(*, rail_pkg_dir, project_dir, priority=60)`：构造时加载并校验 rail 包内的 config.yaml，校验失败直接抛 ValueError，让构建方（BC-005）拒绝挂载，Agent 永远不会装载损坏的状态机；成功后 `self.stages` 取自配置，`priority` 可被配置中的 `priority` 键覆盖。第二个入口是 `after_tool_call(ctx)`：仅当工具名为 `ask_user` 且当前阶段是评审阶段（analysis_review/design_review）时才处理确认点——含拒绝关键词（中英词表，ASCII 用词边界正则）的答案按 `_REWORK_TARGETS` 迁回对应生产阶段；approve 不自动迁移，等 Agent 显式调用 sdd_advance（避免双推进）；答案为空（失败/非交互）则不迁移。
+
+Sources / 来源：[jiuwenswarm/agents/harness/code/rails/sdd/design_rail/rail.py:L70–L92](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/code/rails/sdd/design_rail/rail.py#L70-L92), [jiuwenswarm/agents/harness/code/rails/sdd/design_rail/rail.py:L97–L149](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/code/rails/sdd/design_rail/rail.py#L97-L149)
+
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-session-messaging-toolkit.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-session-messaging-toolkit.md
new file mode 100644
index 00000000..d9e378da
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-session-messaging-toolkit.md
@@ -0,0 +1,72 @@
+---
+title: "SessionMessagingToolkit 跨会话消息六工具"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py:L435-L600, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py:L344-L356, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py:L319-L342, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py:L325-L328, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py:L358-L363, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py:L489-L497, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py:L566-L568, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py:L470-L477, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py:L555-L560, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py:L537-L544, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py:L603-L613, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py:L321-L342, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py:L350-L356, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:tests/unit_tests/agentserver/test_session_messaging.py:L16-L36, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:tests/unit_tests/agentserver/test_session_messaging.py:L465-L513, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:tests/unit_tests/agentserver/test_session_messaging.py:L562-L591, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:tests/unit_tests/agentserver/test_session_messaging.py:L784-L852]
+feature: "session-messaging-toolkit"
+entry_points: ["jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py"]
+source_globs: ["jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py"]
+---
+
+# SessionMessagingToolkit 跨会话消息六工具
+
+<!-- kb:knowledge owner=feature-session-messaging-toolkit facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**六个 LocalFunction 工具与统一错误返回**
+
+Toolkit 通过 get_tools() 暴露六个 LocalFunction 工具：session_list、session_send_message、session_message_list、session_continue_queued、session_read、session_message_resolve，每个绑定到对应的 async 方法。所有方法在 SessionMessagingError 时统一返回 `{"accepted": False, "code": ..., "error": ...}` 而非抛异常。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py:L435–L600](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py#L435-L600), [jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py:L344–L356](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py#L344-L356)
+
+<!-- kb:knowledge owner=feature-session-messaging-toolkit facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**调用期解析宿主服务与路由，工具保持稳定**
+
+Toolkit 是薄壳：每次调用通过 `_service_and_route()` 在运行时解析宿主服务（`runtime.session_message_service` 兜底）与当前 SessionMessagingRoute；服务缺失或路由不完整时抛出 code 为 `HOST_CAPABILITY_UNAVAILABLE` 的 SessionMessagingError。因此 Tool 对象在 AgentServer Runtime 重建后保持稳定（`set_service` 用于刷新宿主），请求所有权（session_id/request_id）延迟到调用时绑定。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py:L319–L342](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py#L319-L342), [jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py:L325–L328](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py#L325-L328)
+
+<!-- kb:knowledge owner=feature-session-messaging-toolkit facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**模式与分页参数（JSON Schema 默认值）**
+
+send_message 的 `input_mode` 枚举为 `steer`/`follow_up`，Python 侧默认 `"steer"`。resolve 的 `resolution` 枚举为 `succeeded`/`cancelled`/`continue_queued`。Schema 中声明的默认值包括 limit 20（session_list、session_read）、50（session_message_list）、max_output_chars 4000，与函数签名的 Python 默认值一致。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py:L358–L363](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py#L358-L363), [jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py:L489–L497](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py#L489-L497), [jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py:L566–L568](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py#L566-L568)
+
+<!-- kb:knowledge owner=feature-session-messaging-toolkit facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**跨会话消息的异步语义与投递边界**
+
+send_message 是异步排队语义：成功仅表示消息已保存并排队，不表示目标已处理；steer 模式在目标计划模式或活跃目标任务时仍会排队等待。session_read 只读不启动任务，按从新到旧返回并以 cursor 翻页，且明确历史内容是数据而非指令（防提示注入）。continue_queued 恢复未执行队列而不重放消息，session_message_resolve 处理 unknown 状态消息。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py:L470–L477](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py#L470-L477), [jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py:L555–L560](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py#L555-L560), [jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py:L537–L544](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py#L537-L544)
+
+<!-- kb:knowledge owner=feature-session-messaging-toolkit facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**无测试证据**
+
+所提供的代码片段不含测试；无法从这些输入中确认针对该 Toolkit 的测试入口或覆盖情况。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py:L603–L613](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py#L603-L613)
+
+<!-- kb:knowledge owner=feature-session-messaging-toolkit facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**错误折叠与服务解析的边界**
+
+Inference / 设计推断（非作者历史意图）：
+
+六个工具方法仅捕获 SessionMessagingError 并折叠为 `{"accepted": False, "code": ..., "error": ...}` 返回；其他异常不会被转换，会照常抛出。宿主服务可在构造时注入保存在 `self._service`，调用时优先使用该值，仅当其为空时才从当前 Runtime 的 `session_message_service` 兜底获取，代价是调用方必须保证 `set_service` 在 Runtime 重建后刷新引用。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py:L321–L342](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py#L321-L342), [jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py:L350–L356](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/session_messaging_toolkit.py#L350-L356)
+
+<!-- kb:knowledge owner=feature-session-messaging-toolkit facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**单元测试入口与覆盖场景**
+
+测试入口是 `tests/unit_tests/agentserver/test_session_messaging.py`（pytest 异步用例），它直接导入 Toolkit、Route、Rail 及底层 SessionMessageService/Store 并针对真实 SQLite 存储驱动验证。两层覆盖：(1) 服务层语义 — 断连持久化后 FIFO 执行（L465）、busy 目标接受消息但排队不执行（L518）、unknown 结果阻塞后续队列且不重放（L562/L595）、unknown 可显式 resolve 而不重放（L635）、重启后按显式请求继续队列（L676）；(2) Toolkit 工具层 — `test_agent_can_discover_read_and_continue_after_restart` 用 SessionMessagingRouteRail + with_session_messaging_route 构造调用上下文，依次调用 list_sessions/list_messages/read_session/并发 continue_queued，断言 finish_current_turn、队列状态与结果历史；另有 read_session 分页截断/跨会话 cursor 拒绝（L855）与本会话继续延迟到用户轮结束（L887）。
+
+Sources / 来源：[tests/unit_tests/agentserver/test_session_messaging.py:L16–L36](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/tests/unit_tests/agentserver/test_session_messaging.py#L16-L36), [tests/unit_tests/agentserver/test_session_messaging.py:L465–L513](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/tests/unit_tests/agentserver/test_session_messaging.py#L465-L513), [tests/unit_tests/agentserver/test_session_messaging.py:L562–L591](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/tests/unit_tests/agentserver/test_session_messaging.py#L562-L591), [tests/unit_tests/agentserver/test_session_messaging.py:L784–L852](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/tests/unit_tests/agentserver/test_session_messaging.py#L784-L852)
+
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-skill-hub.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-skill-hub.md
index ba84aea0..3c0fead1 100644
--- a/knowledge/repos/jiuwenswarm/components/agents-team/feature-skill-hub.md
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-skill-hub.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/技能.md
 feature: "skill-hub"
 entry_points: ["jiuwenswarm/server/runtime/marketplace/hub_client.py"]
-source_globs: ["jiuwenswarm/server/runtime/marketplace/hub_client.py", "jiuwenswarm/server/runtime/marketplace/*"]
+source_globs: ["jiuwenswarm/server/runtime/marketplace/hub_client.py", "jiuwenswarm/server/runtime/marketplace/*", "jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublication.ts", "jiuwenswarm/channels/web/frontend/src/components/AssetPublishDrawer/index.tsx", "jiuwenswarm/channels/web/frontend/src/components/AssetPublishDrawer/style.css", "jiuwenswarm/channels/web/frontend/src/services/assetPublishApi.ts", "jiuwenswarm/server/runtime/skill/skill_manager.py", "jiuwenswarm/channels/web/frontend/src/features/ClawHubSearchModal/index.tsx", "jiuwenswarm/channels/web/frontend/src/features/SourceManagerModal/index.tsx", "jiuwenswarm/server/runtime/marketplace/hub_asset_installer.py", "jiuwenswarm/server/runtime/marketplace/hub_asset_port.py", "jiuwenswarm/server/runtime/marketplace/asset_publish_api.py", "jiuwenswarm/server/runtime/marketplace/asset_publish_models.py", "jiuwenswarm/server/runtime/marketplace/asset_publish_service.py", "jiuwenswarm/server/runtime/marketplace/asset_publish_store.py", "jiuwenswarm/server/runtime/marketplace/hub_asset_type_adapter.py", "jiuwenswarm/server/runtime/marketplace/hub_avatar_cache.py", "jiuwenswarm/server/runtime/marketplace/hub_catalog_cache.py", "jiuwenswarm/server/runtime/marketplace/hub_install_state.py", "jiuwenswarm/server/runtime/marketplace/hub_package_downloader.py", "jiuwenswarm/server/runtime/marketplace/hub_publish_client.py", "jiuwenswarm/server/runtime/marketplace/hub_publish_port.py", "jiuwenswarm/channels/web/frontend/src/components/marketplace/CatalogCacheNotice.tsx", "jiuwenswarm/channels/web/frontend/src/components/marketplace/InstallationFilterSelect.tsx", "jiuwenswarm/channels/web/frontend/src/components/marketplace/MarketplaceSurface.tsx", "jiuwenswarm/channels/web/frontend/src/components/marketplace/PublicationDetailStatus.tsx", "jiuwenswarm/server/runtime/marketplace/asset_package_builder.py", "jiuwenswarm/channels/web/frontend/src/features/OnlineSkillSearchPanel/index.tsx", "jiuwenswarm/channels/web/frontend/src/components/SkillPanel/useHubMarketplace.ts", "jiuwenswarm/channels/web/frontend/src/components/SkillPanel/MarketplaceView.tsx", "jiuwenswarm/channels/web/frontend/src/utils/gitcodeOAuth.ts", "jiuwenswarm/server/runtime/marketplace/asset_publish_adapters.py", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/teamskills.ts", "jiuwenswarm/channels/web/frontend/src/features/TeamSkillsHubModal/index.tsx"]
 ---
 
 # Skill Hub 与市场流通 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-skills.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-skills.md
index 963c56bf..f2ddd9d3 100644
--- a/knowledge/repos/jiuwenswarm/components/agents-team/feature-skills.md
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-skills.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/技能.md
 feature: "skills"
 entry_points: ["jiuwenswarm/server/runtime/skill/skill_manager.py"]
-source_globs: ["jiuwenswarm/server/runtime/skill/skill_manager.py", "jiuwenswarm/server/runtime/skill/*"]
+source_globs: ["jiuwenswarm/server/runtime/skill/skill_manager.py", "jiuwenswarm/server/runtime/skill/*", "jiuwenswarm/agents/harness/common/tools/skill_toolkits.py", "jiuwenswarm/server/runtime/skill/skills_multipart_http.py", "jiuwenswarm/server/runtime/skill/skillpack.py", "jiuwenswarm/common/utils.py", "jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/md_parser.py", "jiuwenswarm/channels/web/frontend/src/utils/skillNetUrl.ts", "jiuwenswarm/channels/web/frontend/src/utils/mySkills.ts", "jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/sync-runtime-skill.js", "jiuwenswarm/server/runtime/agent_adapter/interface_deep.py", "jiuwenswarm/server/runtime/skill/archive_store.py", "jiuwenswarm/server/runtime/skill/skill_content_images.py", "jiuwenswarm/channels/web/frontend/src/components/SkillPanel/skillPanelUtils.ts", "jiuwenswarm/channels/web/frontend/src/utils/skillPackageFile.ts", "jiuwenswarm/agents/harness/common/tools/send_file_to_user.py", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/SkillPickerPanel.tsx", "jiuwenswarm/server/runtime/skill/skilldev/state_utils.py", "jiuwenswarm/server/runtime/skill/skill_type.py", "jiuwenswarm/channels/web/frontend/src/components/SkillPanel/skillVersionOptions.ts", "jiuwenswarm/server/runtime/skill/skill_files.py", "jiuwenswarm/channels/web/frontend/src/features/SkillNetSearchModal/index.tsx", "jiuwenswarm/server/runtime/agent_adapter/interface.py", "jiuwenswarm/server/agent_ws_server.py", "jiuwenswarm/agents/swarm/providers/member_rails.py", "jiuwenswarm/agents/harness/team/rails/team_member_skill_toolkit_rail.py", "jiuwenswarm/agents/harness/team/rails/team_skill_library_reload_rail.py", "jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/url_safety.py", "jiuwenswarm/channels/web/frontend/src/components/SkillPanel/index.tsx", "jiuwenswarm/channels/web/app_web.py", "jiuwenswarm/channels/browser/frontend/src/webview/chat.html"]
 ---
 
 # 技能安装、挂载与发现 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-subagents.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-subagents.md
index fb20a13f..6401d930 100644
--- a/knowledge/repos/jiuwenswarm/components/agents-team/feature-subagents.md
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-subagents.md
@@ -11,7 +11,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/Harness.md
 feature: "subagents"
 entry_points: ["jiuwenswarm/agents/swarm/providers/code_subagents.py", "jiuwenswarm/agents/harness/common/tools/subagent_compat.py"]
-source_globs: ["jiuwenswarm/agents/swarm/providers/code_subagents.py", "jiuwenswarm/agents/harness/common/tools/subagent_compat.py", "jiuwenswarm/agents/harness/common/rails/*"]
+source_globs: ["jiuwenswarm/agents/swarm/providers/code_subagents.py", "jiuwenswarm/agents/harness/common/tools/subagent_compat.py", "jiuwenswarm/agents/harness/common/rails/*", "jiuwenswarm/server/runtime/agent_config_service.py", "jiuwenswarm/agents/harness/common/prompt/browser_task_prompt.py", "jiuwenswarm/agents/harness/common/rails/browser_task_prompt_rail.py", "jiuwenswarm/server/runtime/agent_adapter/interface_deep.py", "jiuwenswarm/agents/harness/common/tools/multi_session_toolkits.py", "jiuwenswarm/common/config.py", "jiuwenswarm/channels/web/frontend/src/types/subagent.ts", "jiuwenswarm/channels/web/frontend/src/components/subagent/Subagent.css", "jiuwenswarm/channels/web/frontend/src/components/subagent/SubagentCompactPanel.tsx", "jiuwenswarm/channels/web/frontend/src/components/subagent/SubagentExpandedPanel.tsx", "jiuwenswarm/channels/web/frontend/src/components/subagent/SubagentStatusIcon.tsx", "jiuwenswarm/agents/swarm/providers/code_rails.py", "jiuwenswarm/server/runtime/agent_adapter/task_tool_events.py", "jiuwenswarm/channels/web/frontend/src/features/subagent/subagentActivityPresentation.ts", "jiuwenswarm/channels/web/frontend/src/features/subagent/subagentStatusPresentation.ts", "jiuwenswarm/channels/web/frontend/src/features/historyRestore.ts", "jiuwenswarm/channels/web/frontend/src/App.tsx", "jiuwenswarm/channels/web/frontend/src/features/subagent/subagentNormalizer.ts", "jiuwenswarm/channels/web/frontend/src/stores/subagentStore.ts"]
 ---
 
 # 子代理派发与验证 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-swarm-skills.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-swarm-skills.md
index 30933fbc..cf94fd42 100644
--- a/knowledge/repos/jiuwenswarm/components/agents-team/feature-swarm-skills.md
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-swarm-skills.md
@@ -11,7 +11,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/SwarmSkills.md
 feature: "swarm-skills"
 entry_points: ["jiuwenswarm/agents/swarm/assembly.py", "jiuwenswarm/agents/swarm/providers/skills.py"]
-source_globs: ["jiuwenswarm/agents/swarm/assembly.py", "jiuwenswarm/agents/swarm/providers/skills.py", "jiuwenswarm/agents/swarm/*"]
+source_globs: ["jiuwenswarm/agents/swarm/assembly.py", "jiuwenswarm/agents/swarm/providers/skills.py", "jiuwenswarm/agents/swarm/*", "jiuwenswarm/agents/swarm/config_specs.py", "jiuwenswarm/agents/swarm/providers/tools.py", "jiuwenswarm/resources/agent/workspace/skills/swarmskill-creator/scripts/validate_swarmskill.py", "jiuwenswarm/server/runtime/agent_adapter/team_helpers.py", "jiuwenswarm/agents/harness/team/rails/team_skill_storage_policy_rail.py"]
 ---
 
 # 团队技能与能力复用 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-swarmflow.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-swarmflow.md
index 54f9d75b..e57cafab 100644
--- a/knowledge/repos/jiuwenswarm/components/agents-team/feature-swarmflow.md
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-swarmflow.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/TUI使用SwarmFlow指南.md
 feature: "swarmflow"
 entry_points: ["jiuwenswarm/agents/harness/team/handlers/workflow_state.py"]
-source_globs: ["jiuwenswarm/agents/harness/team/handlers/workflow_state.py", "jiuwenswarm/agents/harness/team/handlers/*"]
+source_globs: ["jiuwenswarm/agents/harness/team/handlers/workflow_state.py", "jiuwenswarm/agents/harness/team/handlers/*", "jiuwenswarm/server/runtime/agent_adapter/team_helpers.py", "jiuwenswarm/channels/web/frontend/src/utils/swarmflowAdvisory.ts", "jiuwenswarm/channels/web/frontend/src/components/teamArea/AgentDetailModal.tsx", "jiuwenswarm/agents/harness/team/team_manager.py", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/InputArea.tsx", "jiuwenswarm/channels/tui/frontend/src/ui/app-screen.ts", "jiuwenswarm/common/config.py", "jiuwenswarm/server/runtime/agent_adapter/interface_deep.py", "jiuwenswarm/server/agent_ws_server.py", "jiuwenswarm/channels/web/frontend/src/components/teamArea/SwarmflowTreeView.tsx", "jiuwenswarm/channels/tui/frontend/src/core/workflows.ts", "jiuwenswarm/channels/web/frontend/src/components/teamArea/workflowTypes.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/swarmflows.ts", "jiuwenswarm/channels/web/frontend/src/App.tsx", "jiuwenswarm/channels/web/frontend/src/components/teamArea/SwarmflowGraphView.tsx", "jiuwenswarm/channels/web/frontend/src/stores/sessionStore.ts", "jiuwenswarm/channels/web/frontend/src/services/webClient.ts", "jiuwenswarm/agents/harness/team/handlers/workflow_monitor_handler.py", "jiuwenswarm/server/wire_truncate.py"]
 ---
 
 # SwarmFlow 工作流与 HITL 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-team.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-team.md
index bb490acd..9d6a786f 100644
--- a/knowledge/repos/jiuwenswarm/components/agents-team/feature-team.md
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-team.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/AgentTeam.md
 feature: "team"
 entry_points: ["jiuwenswarm/agents/harness/team/team_manager.py"]
-source_globs: ["jiuwenswarm/agents/harness/team/team_manager.py", "jiuwenswarm/agents/harness/team/*.py"]
+source_globs: ["jiuwenswarm/agents/harness/team/team_manager.py", "jiuwenswarm/agents/harness/team/*.py", "jiuwenswarm/agents/swarm/agent_group.py", "jiuwenswarm/server/runtime/extension_package_manager.py", "jiuwenswarm/agents/harness/team/bootstrap.py", "jiuwenswarm/common/config.py", "jiuwenswarm/channels/ide/packages/vscode-extension/src/swarm/SwarmMapPanel.ts", "jiuwenswarm/channels/ide/packages/vscode-extension/src/swarm/SwarmState.ts", "jiuwenswarm/channels/ide/packages/vscode-extension/src/swarm/SwarmStateManager.ts", "jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/swarm/SwarmState.kt", "jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/swarm/SwarmStateManager.kt", "jiuwenswarm/agents/swarm/providers/tools.py", "jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/ChatToolWindow.kt", "jiuwenswarm/channels/ide/packages/shared-webview/swarm_map.html", "jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/SwarmMapPanel.kt", "jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/SwarmMapToolWindowFactory.kt", "jiuwenswarm/agents/swarm/__init__.py", "jiuwenswarm/agents/swarm/assembly.py", "jiuwenswarm/server/runtime/agent_adapter/team_helpers.py", "jiuwenswarm/channels/web/frontend/src/components/teamArea/shared.tsx", "jiuwenswarm/server/agent_ws_server.py", "jiuwenswarm/server/runtime/team_binding_store.py", "jiuwenswarm/agents/harness/team/config_loader.py", "jiuwenswarm/agents/harness/common/tools/send_file_to_user.py", "jiuwenswarm/agents/harness/team/event_types.py", "jiuwenswarm/channels/web/frontend/src/components/teamArea/TeamMembersPanel.tsx", "jiuwenswarm/channels/web/frontend/src/utils/teamMemberAvatar.ts", "jiuwenswarm/channels/web/frontend/src/components/TeamMemberAvatar/index.tsx", "jiuwenswarm/channels/web/frontend/src/components/teamArea/MemberListItem.tsx", "jiuwenswarm/channels/web/frontend/src/components/teamArea/MemberOverviewCard.tsx", "jiuwenswarm/agents/harness/team/__init__.py", "jiuwenswarm/agents/harness/team/handlers/team_monitor_handler.py", "jiuwenswarm/agents/harness/team/handlers/base_monitor_handler.py", "jiuwenswarm/agents/harness/team/rails/team_workspace_report_path_rail.py", "jiuwenswarm/agents/harness/team/team_name_generator.py", "jiuwenswarm/channels/tui/frontend/src/ui/components/team-panel.ts", "jiuwenswarm/channels/tui/frontend/src/ui/app-screen.ts", "jiuwenswarm/channels/tui/frontend/src/ui/components/team-shared.ts", "jiuwenswarm/channels/tui/frontend/src/ui/components/team-status-pill.ts", "jiuwenswarm/channels/tui/frontend/src/core/event-handlers.ts", "jiuwenswarm/channels/web/frontend/src/hooks/useWebSocket.ts", "jiuwenswarm/channels/web/frontend/src/features/teamConnectionPresentation.ts", "jiuwenswarm/channels/web/frontend/src/App.tsx", "jiuwenswarm/channels/web/frontend/src/features/teamLeaderIdentity.ts", "jiuwenswarm/channels/web/frontend/src/stores/sessionStore.ts", "jiuwenswarm/channels/web/frontend/src/components/teamArea/ProcessListCard.tsx", "jiuwenswarm/channels/web/frontend/src/stores/teamTaskNormalize.ts", "jiuwenswarm/channels/web/frontend/src/features/teamTaskProgressBaseline.ts"]
 ---
 
 # 多智能体团队协作 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-user-todos-tool.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-user-todos-tool.md
new file mode 100644
index 00000000..4f9cc877
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-user-todos-tool.md
@@ -0,0 +1,64 @@
+---
+title: "user_todos Personal Per-Channel Todo Tool"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L22-L32, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L276-L283, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L364-L374, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L196-L201, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L109-L124, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L141-L158, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L182-L191, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L17-L19, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L93-L106, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L243-L244, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L292-L292, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L163-L179, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L202-L207, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L114-L116, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L344-L346, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L384-L395, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L194-L230, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L255-L272, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L398-L400]
+feature: "user-todos-tool"
+entry_points: ["jiuwenswarm/agents/harness/common/tools/user_todo_tool.py"]
+source_globs: ["jiuwenswarm/agents/harness/common/tools/user_todo_tool.py"]
+---
+
+# user_todos Personal Per-Channel Todo Tool
+
+<!-- kb:knowledge owner=feature-user-todos-tool facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**Supported Behavior**
+
+Full CRUD plus search over per-channel todo items: statuses pending/in_progress/completed/cancelled, priorities high/medium/low, optional ISO-format `due_at`/`remind_at`, and free-text description. On create, if `due_at` is given without `remind_at`, a reminder is auto-derived five minutes before the due time (empty string if parsing fails). Search is a case-insensitive substring match over title and description. The tool description scopes it to the user's personal todos and explicitly steers agents away from using it for internal agent task planning (todo_create/todo_insert).
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L22–L32](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/user_todo_tool.py#L22-L32), [jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L276–L283](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/user_todo_tool.py#L276-L283), [jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L364–L374](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/user_todo_tool.py#L364-L374), [jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L196–L201](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/user_todo_tool.py#L196-L201)
+
+<!-- kb:knowledge owner=feature-user-todos-tool facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**存储与数据流**
+
+每个频道的待办存储为单个 Markdown 文件 `<workspace>/memory/user_todos/<sanitized_channel_id>.md`,条目用 YAML frontmatter(id/title/status/priority 等)加正文 description 序列化;频道 ID 取 `params.channel_id or ContextVar`。读取用正则切分 frontmatter 块,逐行按第一个冒号拆成键值;`TodoItem.from_dict` 抛异常的条目记录 warning 跳过,而没有 id 的块或未被正则匹配的内容则被静默忽略。写路径(create/update/delete)先整体重读文件、修改内存列表,再整体重写文件。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L109–L124](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/user_todo_tool.py#L109-L124), [jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L141–L158](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/user_todo_tool.py#L141-L158), [jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L182–L191](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/user_todo_tool.py#L182-L191)
+
+<!-- kb:knowledge owner=feature-user-todos-tool facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**配置与作用域**
+
+工作区目录由模块级全局变量 `_global_workspace_dir`(初始 ".")通过 `set_global_workspace_dir` 设置,决定 todos 目录基路径。频道与创建者通过 ContextVar 提供,默认分别为 "default" 和空串,可在每协程用 `set_global_channel_id`/`set_global_created_by` 覆盖。优先级用 `or` 实现:显式传入的空字符串(如 `params.channel_id=""`)会回落到 ContextVar 值(L243、L292);created_by 回落仅在 create 分支生效,update 分支对任何非 None 的 created_by(包括空串)直接赋值(L327-L328)。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L17–L19](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/user_todo_tool.py#L17-L19), [jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L93–L106](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/user_todo_tool.py#L93-L106), [jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L243–L244](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/user_todo_tool.py#L243-L244), [jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L292–L292](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/user_todo_tool.py#L292-L292)
+
+<!-- kb:knowledge owner=feature-user-todos-tool facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**设计取舍**
+
+Inference / 设计推断（非作者历史意图）：
+
+选择 Markdown+frontmatter 单文件作为存储,使内容对人和其他工具可直接读改,但读写是自定义的简化解析器(正则切块、按第一个冒号拆行),而非完整 YAML。变更操作采用读-改-整体重写:create 在 L297、update 在 L334、delete 在 L355 调用 `_write_todos_file` 重写整个文件,而 list/get/search 只读;所示代码中没有文件锁,并发写可能互相覆盖(推断,基于缺少锁机制的实现方式)。代码注释说明因模块级单例状态,工具以 `stateless=True` 注册为所有 agent 共享的单一注册。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L163–L179](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/user_todo_tool.py#L163-L179), [jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L202–L207](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/user_todo_tool.py#L202-L207), [jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L182–L191](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/user_todo_tool.py#L182-L191)
+
+<!-- kb:knowledge owner=feature-user-todos-tool facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**输入校验与错误路径**
+
+所示代码中的校验全部是内联检查:未知 action 返回带合法 action 列表的错误;get/update/delete 要求 todo_id、create 要求 title、search 要求 query,缺失即返回 success=False;channel_id 经 `_sanitize_channel_id` 把非 `[a-zA-Z0-9_-]` 字符替换为下划线以防止路径穿越。状态/优先级字符串在 create/update 中直接构造 `TodoStatus(...)`/`TodoPriority(...)`,非法值抛出的异常由 `_handle_user_todos` 外层 except 捕获并转为错误字典。本片段未包含测试文件。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L114–L116](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/user_todo_tool.py#L114-L116), [jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L344–L346](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/user_todo_tool.py#L344-L346), [jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L384–L395](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/user_todo_tool.py#L384-L395)
+
+<!-- kb:knowledge owner=feature-user-todos-tool facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**user_todos 入口与调用契约**
+
+公开入口是 `@tool(name="user_todos", stateless=True)` 装饰的异步函数 `user_todos(params)`，另有 `get_decorated_tools()` 返回该工具的列表供注册。入参为 `UserTodosParams` dataclass（或 dict——入口会把 dict 按字段名过滤后转换），`action` 必填，取值 list/get/create/update/delete/search；get/update/delete 要求 `todo_id`，create 要求 `title`，search 要求 `query`，这些必需参数的检查位于各自 action 分支内部。返回值为字典：成功时含 `success: True`（list/search 附 `todos`/`count`，get/create/update 附 `todo`），失败时含 `success: False` 与 `error` 字符串。非法 status/priority 等运行期异常由 `_handle_user_todos` 外层 except 捕获并转为 `{"success": False, "error": str(e)}`，不向调用方抛出。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L194–L230](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/user_todo_tool.py#L194-L230), [jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L255–L272](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/user_todo_tool.py#L255-L272), [jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L384–L395](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/user_todo_tool.py#L384-L395), [jiuwenswarm/agents/harness/common/tools/user_todo_tool.py:L398–L400](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/user_todo_tool.py#L398-L400)
+
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-video-generation-tools.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-video-generation-tools.md
new file mode 100644
index 00000000..7963ebfa
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-video-generation-tools.md
@@ -0,0 +1,46 @@
+---
+title: "generate_video / check_video_status 提交后轮询的视频生成工具"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/video_gen_tools.py:L14-L21, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/video_gen_tools.py:L48-L79, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/video_gen_tools.py:L258-L258, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/gen_toolkits.py:L147-L162, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/gen_toolkits.py:L354-L376, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/gen_toolkits.py:L622-L642, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/video_gen_tools.py:L132-L143, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/video_gen_tools.py:L170-L174, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/video_gen_tools.py:L211-L222, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/gen_toolkits.py:L98-L99, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/gen_toolkits.py:L77-L77, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/video_gen_tools.py:L152-L169, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/video_gen_tools.py:L175-L184, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/video_gen_tools.py:L208-L222]
+feature: "video-generation-tools"
+entry_points: ["jiuwenswarm/agents/harness/common/tools/video_gen_tools.py"]
+source_globs: ["jiuwenswarm/agents/harness/common/tools/video_gen_tools.py", "jiuwenswarm/agents/harness/common/tools/gen_toolkits.py"]
+---
+
+# generate_video / check_video_status 提交后轮询的视频生成工具
+
+<!-- kb:knowledge owner=feature-video-generation-tools facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**配置项与后端选择**
+
+凭据只来自 "Video processing" 配置槽的三个环境变量：`VIDEO_GEN_API_KEY`、`VIDEO_GEN_API_BASE`、`VIDEO_GEN_MODEL_NAME`，无回退变量、无内置默认端点或模型，三者（check_video_status 仅前两者）非空才算已配置。`VIDEO_GEN_ENABLED` 是独立的开关门（"1"/"true"/"yes"/"on" 视为开启），与凭据是否完整互不影响。后端选择由 `VIDEO_GEN_PROTOCOL` 环境变量（detect_backend 的第一个参数指定其名字）或 API URL 主机名推断：minimax/modelark 域名命中即返回对应后端，否则 None 走 OpenRouter 路径。模块 docstring 还提到 VIDEO_GEN_PROVIDER 属于该配置槽，但代码中未见其被读取。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/video_gen_tools.py:L14–L21](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/video_gen_tools.py#L14-L21), [jiuwenswarm/agents/harness/common/tools/video_gen_tools.py:L48–L79](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/video_gen_tools.py#L48-L79), [jiuwenswarm/agents/harness/common/tools/video_gen_tools.py:L258–L258](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/video_gen_tools.py#L258-L258), [jiuwenswarm/agents/harness/common/tools/gen_toolkits.py:L147–L162](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/gen_toolkits.py#L147-L162)
+
+<!-- kb:knowledge owner=feature-video-generation-tools facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的行为与厂商后端**
+
+支持文本生视频与可选首帧图（本地路径/URL/data: URI）的图生视频；generate_audio 开关仅在后端支持时生效（MiniMax H3 后端无音频开关，构造请求体时不传入该字段）。厂商后端各自做参数映射：MiniMax 把 resolution 映射为 "768P"/"2K"、ratio 不在集合内回退 "16:9"；ModelArk 分辨率不在 {480p,720p,1080p} 时回退 "720p"，有首帧时 ratio 用 "adaptive" 以跟随首帧比例，并传递 generate_audio 与 watermark=False。完成视频会下载为本地持久副本（远端 URL 限时失效）。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/gen_toolkits.py:L354–L376](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/gen_toolkits.py#L354-L376), [jiuwenswarm/agents/harness/common/tools/gen_toolkits.py:L622–L642](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/gen_toolkits.py#L622-L642), [jiuwenswarm/agents/harness/common/tools/video_gen_tools.py:L132–L143](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/video_gen_tools.py#L132-L143)
+
+<!-- kb:knowledge owner=feature-video-generation-tools facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**有界轮询与平面参数签名**
+
+提交后同步轮询的预算以 sleep 时长累计（每轮 sleep 10s 后累加 10s），OpenRouter/MiniMax 路径为 120s、ModelArk 为 300s（依据是 5s Seedance 片段约需 2.5 分钟渲染）；预算只计入 sleep 时间，不含 HTTP 请求耗时，超时后返回 job_id 让 agent 改调 check_video_status，而不是无限阻塞。docstring 记录了刻意保留平面参数签名而非 dataclass/BaseModel 的理由：CallableSchemaExtractor 会把 dataclass 参数压成无属性的 object schema，而 BaseModel 会改变调用约定，属行为变更。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/video_gen_tools.py:L170–L174](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/video_gen_tools.py#L170-L174), [jiuwenswarm/agents/harness/common/tools/video_gen_tools.py:L211–L222](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/video_gen_tools.py#L211-L222), [jiuwenswarm/agents/harness/common/tools/gen_toolkits.py:L98–L99](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/gen_toolkits.py#L98-L99), [jiuwenswarm/agents/harness/common/tools/gen_toolkits.py:L77–L77](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/gen_toolkits.py#L77-L77)
+
+<!-- kb:knowledge owner=feature-video-generation-tools facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**错误路径处理与作者自述的验证**
+
+在展示的输入中没有可供引用的测试入口点。代码内可核的验证证据是：`_poll_job` 把非 200 轮询响应和非法 JSON 作为返回错误上报而非抛出（docstring 说明 RuntimeError/JSONDecodeError 不属于外层 `except httpx.HTTPError`，此前会让工具调用崩溃），并用调用方已知的提交响应作为种子以免已终止的 job 丢失 error 字段。generate_video 的函数 docstring（非模块 docstring）自述曾直接对照 `CallableSchemaExtractor.get_type_schema` 验证过 dataclass 参数会坍缩为空 object schema——这是作者声明，未见配套测试。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/video_gen_tools.py:L152–L169](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/video_gen_tools.py#L152-L169), [jiuwenswarm/agents/harness/common/tools/video_gen_tools.py:L175–L184](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/video_gen_tools.py#L175-L184), [jiuwenswarm/agents/harness/common/tools/video_gen_tools.py:L208–L222](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/video_gen_tools.py#L208-L222)
+
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-web-search-tools.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-web-search-tools.md
new file mode 100644
index 00000000..fc042e7b
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-web-search-tools.md
@@ -0,0 +1,58 @@
+---
+title: "MCP Free/Paid Search Tools with Trusted-Search Provenance Lease"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/search_tools.py:L36-L39, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/settings/modules/agent/AgentSettings.tsx:L96-L110, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/search_tools.py:L302-L328, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/search_tools.py:L570-L594, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/trusted_search_tool_adapter.py:L3-L8, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/search_tools.py:L184-L215, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/search_tools.py:L567-L594, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/trusted_search_tool_adapter.py:L67-L71, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/trusted_search_tool_adapter.py:L36-L55, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/trusted_search_tool_adapter.py:L84-L99, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/trusted_search_tool_adapter.py:L120-L135, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/trusted_search_tool_adapter.py:L50-L71, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/trusted_search_tool_adapter.py:L92-L114, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/search_tools.py:L584-L594]
+feature: "web-search-tools"
+entry_points: ["jiuwenswarm/agents/harness/common/tools/trusted_search_tool_adapter.py"]
+source_globs: ["jiuwenswarm/agents/harness/common/tools/trusted_search_tool_adapter.py", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/agent/AgentSettings.tsx", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/agent/definition.ts", "jiuwenswarm/agents/harness/common/tools/search_tools.py"]
+---
+
+# MCP Free/Paid Search Tools with Trusted-Search Provenance Lease
+
+<!-- kb:knowledge owner=feature-web-search-tools facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证入口**
+
+Inference / 设计推断（非作者历史意图）：
+
+本次展示的输入中未包含测试文件，无法从证据中指出该功能的测试入口；未出现在部分输入中不证明测试不存在。可观察的运行时校验行为包括：`normalize_search_max_results` 与 timeout 夹取、前端表单必填校验（blur 触发的非空 validator）及保存失败错误展示。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/search_tools.py:L36–L39](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/search_tools.py#L36-L39), [jiuwenswarm/channels/web/frontend/src/features/settings/modules/agent/AgentSettings.tsx:L96–L110](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/settings/modules/agent/AgentSettings.tsx#L96-L110)
+
+<!-- kb:knowledge owner=feature-web-search-tools facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**已实现行为**
+
+免费搜索支持 duckduckgo、duckduckgo-jina（经 r.jina.ai）与 bing 三种引擎，但只有被环境变量启用的引擎才会尝试，按顺序取第一个返回非空结果的引擎。付费搜索在 `provider="auto"` 时按配置了密钥的 provider 顺序依次尝试，首个成功的 runner 结果即返回（并非遍历全部）；指定 provider 若未配置密钥则回退到已配置列表。provenance 集成在适配器文档串中明确为可选（optional one-shot lease）。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/search_tools.py:L302–L328](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/search_tools.py#L302-L328), [jiuwenswarm/agents/harness/common/tools/search_tools.py:L570–L594](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/search_tools.py#L570-L594), [jiuwenswarm/agents/harness/common/tools/trusted_search_tool_adapter.py:L3–L8](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/trusted_search_tool_adapter.py#L3-L8)
+
+<!-- kb:knowledge owner=feature-web-search-tools facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**设计取舍**
+
+Inference / 设计推断（非作者历史意图）：
+
+免费引擎用正则解析 HTML/Markdown（result__a、b_algo 块、r.jina.ai 的 markdown 链接），并对 DDG 反爬页（202/418/429/503 或 anomaly.js 标记）显式报错后回退到下一引擎——无需官方 API，但依赖页面结构，易随布局变化失效。付费搜索提供多 provider 回退与密钥缺失时跳过 runner 的保护（注释说明队列中的调用可能超出 provider 配置存活期），但没有任何已配置密钥时仍会直接失败，并非可用性保证；provenance lease 的一次性关闭语义依赖未展示的 `complete_trusted_search_producer` 实现，此处只能确认 `finally` 中无条件调用 `success=False`。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/search_tools.py:L184–L215](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/search_tools.py#L184-L215), [jiuwenswarm/agents/harness/common/tools/search_tools.py:L567–L594](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/search_tools.py#L567-L594), [jiuwenswarm/agents/harness/common/tools/trusted_search_tool_adapter.py:L67–L71](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/trusted_search_tool_adapter.py#L67-L71)
+
+<!-- kb:knowledge owner=feature-web-search-tools facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**公开工具入口与调用契约**
+
+适配器导出两个 MCP 工具对象：`mcp_free_search`（query、max_results=8、timeout_seconds=20）与 `mcp_paid_search`（额外 provider="auto"，timeout 默认 45）。两者都会对入参做夹取：max_results 经 `normalize_search_max_results` 夹到 1–20，timeout 分别夹到 5–60 与 10–120；空 query 或 free/paid 搜索失败时返回 `[ERROR]: ...` 字符串而不是抛异常（`_run_paid_search` 还会在内部把 provider 规范化并校验为 auto/bocha/jina/serper/perplexity，`_ConfiguredPaidSearchTool.invoke` 会把未配置密钥的 provider 重写为 auto 后再交给 LocalFunction 校验）。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/trusted_search_tool_adapter.py:L36–L55](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/trusted_search_tool_adapter.py#L36-L55), [jiuwenswarm/agents/harness/common/tools/trusted_search_tool_adapter.py:L84–L99](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/trusted_search_tool_adapter.py#L84-L99), [jiuwenswarm/agents/harness/common/tools/trusted_search_tool_adapter.py:L120–L135](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/trusted_search_tool_adapter.py#L120-L135), [jiuwenswarm/agents/harness/common/tools/search_tools.py:L36–L39](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/search_tools.py#L36-L39)
+
+<!-- kb:knowledge owner=feature-web-search-tools facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**职责分层与执行/溯源数据流**
+
+`search_tools.py` 是中立的搜索实现（不注册工具、不依赖权限设施），`trusted_search_tool_adapter.py` 是唯一的 MCP Tool 对象 owner 并桥接溯源租约。执行路径不对称：free 适配器自己用 `asyncio.to_thread(run_free_search_structured, ...)` 包装同步实现；paid 适配器直接 `await run_paid_search_structured(...)`，由该 async 函数内部对每个同步 runner 再 `asyncio.to_thread`。两个工具成功时都在渲染结果之前调用 `complete_trusted_search_producer(success=True, urls=...)` 提交结构化 URL，`finally` 中再以 `success=False` 无条件收尾（一次性租约语义，成功提交在前即已生效）。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/trusted_search_tool_adapter.py:L3–L8](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/trusted_search_tool_adapter.py#L3-L8), [jiuwenswarm/agents/harness/common/tools/trusted_search_tool_adapter.py:L50–L71](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/trusted_search_tool_adapter.py#L50-L71), [jiuwenswarm/agents/harness/common/tools/trusted_search_tool_adapter.py:L92–L114](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/trusted_search_tool_adapter.py#L92-L114), [jiuwenswarm/agents/harness/common/tools/search_tools.py:L584–L594](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/search_tools.py#L584-L594)
+
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-alarm-crud.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-alarm-crud.md
new file mode 100644
index 00000000..1f6a1d51
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-alarm-crud.md
@@ -0,0 +1,46 @@
+---
+title: "小艺手机工具 — 设备闹钟 CRUD（create/search/modify/delete_alarm）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/alarm_tools.py:L320-L333, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/alarm_tools.py:L263-L288, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/utils.py:L58-L96, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/utils.py:L168-L207, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/alarm_tools.py:L596-L601, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/alarm_tools.py:L205-L221, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/utils.py:L87-L104, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/alarm_tools.py:L263-L278, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/alarm_tools.py:L286-L292, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/utils.py:L210-L228]
+feature: "xiaoyi-alarm-crud"
+entry_points: ["jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/alarm_tools.py"]
+source_globs: ["jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/alarm_tools.py", "jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/utils.py", "jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/calendar_tools.py", "jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py"]
+---
+
+# 小艺手机工具 — 设备闹钟 CRUD（create/search/modify/delete_alarm）
+
+<!-- kb:knowledge owner=feature-xiaoyi-alarm-crud facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证入口未在所示范围内出现**
+
+所示片段不包含任何测试文件或测试引用；本任务无法基于这些证据描述该功能的测试入口与覆盖情况。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/alarm_tools.py:L320–L333](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/alarm_tools.py#L320-L333)
+
+<!-- kb:knowledge owner=feature-xiaoyi-alarm-crud facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**命令构造 + 共享通道执行**
+
+每个工具本地校验参数并构造一个 `header: Common/Action` 命令，`executeParam` 固定指向 `bundleName: com.huawei.hmos.clock` 与对应 intentName（CreateAlarm/SearchAlarm/ModifyAlarm/DeleteAlarm），然后交给共享的 `execute_device_command`。该函数从 runtime 取 xiaoyi channel，从 config 读会话标识，注册按 `intent_name` 匹配的 data-event 处理器，`asyncio.wait_for` 默认 60 秒等待响应，并在 finally 中注销处理器。`delete_alarm` 的输入归一化委托给未在节选中展示的 `_normalize_delete_items`。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/alarm_tools.py:L263–L288](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/alarm_tools.py#L263-L288), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/utils.py:L58–L96](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/utils.py#L58-L96), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/utils.py:L168–L207](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/utils.py#L168-L207), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/alarm_tools.py:L596–L601](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/alarm_tools.py#L596-L601)
+
+<!-- kb:knowledge owner=feature-xiaoyi-alarm-crud facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**创建默认值、枚举校验与会话配置**
+
+`create_alarm` 在参数缺省时填入默认值：标题 "闹钟"、`alarm_snooze_duration=10`、`alarm_snooze_total=0`、`alarm_ring_duration=5`、`days_of_wake_type=0`，随后对枚举型字段做成员校验（合法值集合定义于未展示的模块级常量 `_ALARM_SNOOZE_DURATION` 等，节选只显示校验逻辑与报错文案）。运行时会话身份从 config 读取：`channels.xiaoyi.last_session_id` / `last_task_id`；缺少有效 session_id 时抛 RuntimeError。命令内常量固定：`timeOut: 5`、`needUnlock: True`、`executeMode: background`。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/alarm_tools.py:L205–L221](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/alarm_tools.py#L205-L221), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/utils.py:L87–L104](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/utils.py#L87-L104), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/alarm_tools.py:L263–L278](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/alarm_tools.py#L263-L278)
+
+<!-- kb:knowledge owner=feature-xiaoyi-alarm-crud facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**所示输入中的验证入口**
+
+所示文件节选（alarm_tools.py、utils.py 及对照的 calendar/contact tools）均为实现代码，不含测试文件或测试引用；本页无法基于这些证据描述该功能的测试入口与覆盖情况。已有的验证手段是运行时防御：参数校验抛 `ToolInputError`、设备错误经 `raise_if_device_error` 检查 `code`/`retErrCode` 后抛 RuntimeError。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/alarm_tools.py:L286–L292](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/alarm_tools.py#L286-L292), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/utils.py:L210–L228](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/utils.py#L210-L228)
+
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-calendar-tools.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-calendar-tools.md
new file mode 100644
index 00000000..df397162
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-calendar-tools.md
@@ -0,0 +1,48 @@
+---
+title: "Xiaoyi 设备日历日程工具（create/search_calendar_event）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/calendar_tools.py:L131-L171, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/calendar_tools.py:L237-L281, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/calendar_tools.py:L106-L110, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/calendar_tools.py:L276-L287, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/calendar_tools.py:L137-L161, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/calendar_tools.py:L244-L261, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/calendar_tools.py:L120-L135, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/calendar_tools.py:L222-L235, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/calendar_tools.py:L264-L274]
+feature: "xiaoyi-calendar-tools"
+entry_points: ["jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/calendar_tools.py"]
+source_globs: ["jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/calendar_tools.py"]
+---
+
+# Xiaoyi 设备日历日程工具（create/search_calendar_event）
+
+<!-- kb:knowledge owner=feature-xiaoyi-calendar-tools facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**职责与数据流**
+
+每个工具是薄适配层：校验输入、把时间字符串转为毫秒时间戳，组装 HarmonyOS 意图命令（header namespace `Common`，create 用 `ActionAndResult`、search 用 `Action`），交给共享的 `execute_device_command` 下发到设备日历（bundle `com.huawei.hmos.calendardata`），再对结果做错误检查与格式化。search 额外从 `result.items` 取日程并用 `_convert_event_timestamps` 把时间戳转成可读格式。命令细节（如 `intentParam` 字段 `dtStart/dtEnd` vs `timeInterval`）在此层静态构造。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/calendar_tools.py:L131–L171](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/calendar_tools.py#L131-L171), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/calendar_tools.py:L237–L281](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/calendar_tools.py#L237-L281)
+
+<!-- kb:knowledge owner=feature-xiaoyi-calendar-tools facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证情况**
+
+Inference / 设计推断（非作者历史意图）：
+
+所示片段仅含实现代码，未见针对这两个工具的测试或断言；代码内仅有运行时日志（`[CALENDAR_TOOL]`/`[SEARCH_CALENDAR_TOOL]`）和异常路径作为可观测性手段。依据部分输入无法确认测试是否存在。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/calendar_tools.py:L106–L110](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/calendar_tools.py#L106-L110), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/calendar_tools.py:L276–L287](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/calendar_tools.py#L276-L287)
+
+<!-- kb:knowledge owner=feature-xiaoyi-calendar-tools facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**命令参数为静态构造**
+
+两个工具的设备命令参数在代码中硬编码：目标 bundle 均为 `com.huawei.hmos.calendardata`，`executeMode: "background"`、`needUnlock: True`、`achieveType: "INTENT"`，payload 中均含 `timeOut: 5`（单位在所示片段中未标注）。差异在于：search 的 `executeParam` 额外含 `appType: "OHOS_APP"` 和 `permissionId: []`，而 create 的注释明确其 executeParam 不含这两项（L137、L251、L254）。所示片段中未出现从环境或配置文件读取的设置项。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/calendar_tools.py:L137–L161](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/calendar_tools.py#L137-L161), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/calendar_tools.py:L244–L261](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/calendar_tools.py#L244-L261)
+
+<!-- kb:knowledge owner=feature-xiaoyi-calendar-tools facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的行为与依赖**
+
+create 将 `yyyy-mm-dd hh:mm:ss` 字符串经 `datetime.strptime` 转为毫秒时间戳，以 `intentParam` 的 `dtStart/dtEnd` 下发 `CreateCalendarEvent` 意图（L122–L135、L147）。search 用模块内辅助 `_parse_time_string_ymd_hhmmss` 解析 `YYYYMMDD hhmmss`，以 `timeInterval` [起, 止] 毫秒区间下发 `SearchCalendarEvent`，可选 `title` 过滤；结果从 `result.items` 取出并经 `_convert_event_timestamps` 转为可读时间（L222–L235、L270–L274）。两者均依赖共享的 `execute_device_command` 下发命令（L164、L265）。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/calendar_tools.py:L120–L135](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/calendar_tools.py#L120-L135), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/calendar_tools.py:L222–L235](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/calendar_tools.py#L222-L235), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/calendar_tools.py:L264–L274](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/calendar_tools.py#L264-L274)
+
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-call-phone-tool.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-call-phone-tool.md
new file mode 100644
index 00000000..c6865868
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-call-phone-tool.md
@@ -0,0 +1,66 @@
+---
+title: "小艺拨打电话工具 (call_phone)"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py:L3-L7, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py:L53-L61, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py:L45-L61, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py:L91-L98, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py:L24-L43, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py:L91-L113, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py:L63-L96, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py:L100-L113, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py:L26-L30, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py:L46-L61, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py:L63-L89, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py:L109-L113]
+feature: "xiaoyi-call-phone-tool"
+entry_points: ["jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py"]
+source_globs: ["jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py"]
+---
+
+# 小艺拨打电话工具 (call_phone)
+
+<!-- kb:knowledge owner=feature-xiaoyi-call-phone-tool facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的行为**
+
+支持通过设备侧意图 `StartCall` 发起电话，可选主卡（slotId=0，默认）或副卡（slotId=1）；`phone_number` 会 strip，空串或非字符串被拒绝。依赖同包 `utils` 提供的 `execute_device_command`、`raise_if_device_error` 与 `ToolInputError`，并复用 `jiuwenswarm.common.utils.logger` 记录调用与失败。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py:L3–L7](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py#L3-L7), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py:L53–L61](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py#L53-L61)
+
+<!-- kb:knowledge owner=feature-xiaoyi-call-phone-tool facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证**
+
+Inference / 设计推断（非作者历史意图）：
+
+所示文件仅含工具实现，未见测试代码；实现的校验逻辑（空号码、slot_id 越界走 ToolInputError，非 dict 输出兜底为空 dict）是可被单测覆盖的分支，但本次输入中没有任何测试文件或测试入口的凭证。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py:L45–L61](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py#L45-L61), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py:L91–L98](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py#L91-L98)
+
+<!-- kb:knowledge owner=feature-xiaoyi-call-phone-tool facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**公开入口与返回契约**
+
+`call_phone(phone_number: str, slot_id: Optional[int])` 经 `@tool(name="call_phone", ...)` 注册为异步工具。成功时返回工具消息结构：`content` 是列表，其中 `content[0]` 为 `{"type": "text"}` 对象，设备回调输出被 `json.dumps` 序列化后放在其 `text` 字段（L100–L107）。注意：L42–L43 的文档字符串声称返回 success/code/phoneNumber/slotId/message 字段，但实现只是把 `execute_device_command` 的输出原样序列化（非 dict 输出在 L93–L94 被替换为 `{}`），并不保证这些字段存在。错误契约：`ToolInputError` 原样抛出（L109–L110），其余任何异常被包装为 `RuntimeError("拨打电话失败: ...")`（L111–L113）。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py:L24–L43](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py#L24-L43), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py:L91–L113](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py#L91-L113)
+
+<!-- kb:knowledge owner=feature-xiaoyi-call-phone-tool facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**职责与数据流**
+
+工具流程：归一化 slot_id 默认值并校验输入（L45–L61），组装 `Common/Action` 设备命令（intentName=StartCall、bundleName=com.huawei.hmos.aidispatchservice、executeMode=background、needUnlock=True，intentParam 携带 phoneNumber/slotId，L63–L89），委托给同包 `utils.execute_device_command("StartCall", command)` 执行（L91），随后对输出做非 dict 兜底为 `{}`、经 `raise_if_device_error` 检查设备错误（L93–L96），再把输出 JSON 序列化并包装为 content 消息返回（L100–L107）；设备执行与错误判定逻辑完全在 `utils` 中，本文件可见部分不含传输细节。异常路径区分 ToolInputError 与兜底 RuntimeError（L109–L113）。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py:L45–L61](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py#L45-L61), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py:L63–L96](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py#L63-L96), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py:L100–L113](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py#L100-L113)
+
+<!-- kb:knowledge owner=feature-xiaoyi-call-phone-tool facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**可调参数与内置常量**
+
+仅有两个输入参数：`phone_number`（必填，strip 后不可为空）与 `slot_id`（未传时按 0 主卡，仅允许 0/1，L46–L61）。其余命令参数均为代码内固定：`timeOut: 5`、`executeMode: "background"`、`needUnlock: True`、`actionResponse: True` 等（L63–L89），不通过外部配置注入。工具描述中向调用方声明：操作超时时间为 60 秒，请勿重复调用此工具；如果超时或失败，最多重试一次（L26–L30）——注意 60 秒是描述文本中的值，命令 payload 内另写死 `timeOut: 5`，两者关系在所示代码中不可见。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py:L26–L30](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py#L26-L30), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py:L46–L61](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py#L46-L61), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py:L63–L89](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py#L63-L89)
+
+<!-- kb:knowledge owner=feature-xiaoyi-call-phone-tool facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**取舍：输入校验前置与命令参数硬编码**
+
+Inference / 设计推断（非作者历史意图）：
+
+工具在调用设备前做严格的前置校验：`phone_number` 必须是非空字符串且 strip 后非空，`slot_id` 仅允许 0/1，违规抛 `ToolInputError` 并原样上抛（L53–L61、L109–L110），使其与其余异常（统一包装为 `RuntimeError("拨打电话失败: ...")`，L111–L113）区分开，调用方可据此区分输入错误与执行失败。代价是：命令 payload 的协议字段（`executeMode: "background"`、`needUnlock: True`、`timeOut: 5`、bundleName 等）全部硬编码在代码中（L63–L89），调用方唯一可调的只有号码与卡槽；且工具描述向调用方声明 60 秒超时（L26–L30），与 payload 内写死的 `timeOut: 5` 之间的关系在所示代码中不可见。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py:L53–L61](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py#L53-L61), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py:L109–L113](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py#L109-L113), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py:L63–L89](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py#L63-L89), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py:L26–L30](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/phone_tools.py#L26-L30)
+
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-collection-tools.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-collection-tools.md
new file mode 100644
index 00000000..dcec4fae
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-collection-tools.md
@@ -0,0 +1,54 @@
+---
+title: "小艺收藏工具（query/add/delete_collection）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py:L75-L106, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py:L310-L330, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py:L342-L373, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py:L29-L34, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py:L126-L146, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py:L293-L303, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py:L27-L48, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py:L103-L117, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py:L386-L390, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py:L49-L49, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py:L182-L185, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py:L305-L308, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py:L386-L387]
+feature: "xiaoyi-collection-tools"
+entry_points: ["jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py"]
+source_globs: ["jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py"]
+---
+
+# 小艺收藏工具（query/add/delete_collection）
+
+<!-- kb:knowledge owner=feature-xiaoyi-collection-tools facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**设备 intent 命令的组装与执行流**
+
+每个工具把入参规范化后组装成一个 HarmonyOS 助手 intent 命令：header 固定为 `namespace=Common, name=Action`，executeParam 固定 `bundleName=com.huawei.hmos.vassistant`、`executeMode=background`、`appType=OHOS_APP`、`timeOut=5`、`achieveType=INTENT`，差异只体现在 `intentName`（QueryCollection/DeleteCollection/AddCollection）和 `intentParam`。命令交给共享的 `execute_device_command` 执行，返回值用 `raise_if_device_error` 做错误判定，非 dict 输出被包成 `{'outputs': ...}`。add_collection 在组装命令前多一步：uri 不以 http/https/file:// 开头时视为本地路径，先经 `upload_local_file_public_url` 上传换取公网 URL。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py:L75–L106](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py#L75-L106), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py:L310–L330](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py#L310-L330), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py:L342–L373](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py#L342-L373)
+
+<!-- kb:knowledge owner=feature-xiaoyi-collection-tools facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的行为与依赖关系**
+
+query_collection 支持全量查询（queryAll="true"，默认）或按 query 语义检索，queryAll 不为 "true" 时 query 必填，否则抛 ToolInputError；返回条目描述了 linkTitle/description/label/linkUrl 字段，提示可用 linkUrl 抓取原文。add_collection 支持四种 dataType：HYPER_LINK/TEXT 要求 content，IMAGE/FILE 要求 uri，非法类型或缺失字段在客户端即被拒绝。delete_collection 的 item_ids 接受数组或 JSON 数组字符串，经 `_normalize_item_ids` 规范化后为空则报错。依赖共享的 `execute_device_command`、`raise_if_device_error`、`ToolInputError`（来自 `.utils`）和 `file_upload_helpers` 的 OBS 上传。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py:L29–L34](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py#L29-L34), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py:L126–L146](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py#L126-L146), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py:L293–L303](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py#L293-L303)
+
+<!-- kb:knowledge owner=feature-xiaoyi-collection-tools facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**公开入口与错误契约**
+
+三个 async 工具通过 `@tool` 装饰器注册：`query_collection(query_all="true", query=None)`、`delete_collection(item_ids)`、`add_collection(data_type, content, uri, source_app_bundle_name, title)`。输入校验失败时抛 `ToolInputError`（如 queryAll 不为 true 且无 query、dataType 非法或对应字段缺失、itemIds 无法解析为数组）。设备返回若非 dict 会被包成 `{"outputs": ...}` 再序列化为 `content[0].text`。任何未被校验拦截的异常（例如 uri 为非字符串时 `uri.startswith` 抛 AttributeError）都会被兜底 except 捕获，以 `RuntimeError` 并通过 `from e` 保留原始异常链后抛出。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py:L27–L48](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py#L27-L48), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py:L293–L303](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py#L293-L303), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py:L103–L117](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py#L103-L117), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py:L386–L390](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py#L386-L390)
+
+<!-- kb:knowledge owner=feature-xiaoyi-collection-tools facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**配置读取：仅本地文件上传路径触发**
+
+配置仅在 `add_collection` 走本地文件上传分支（uri 不以 http://、https://、file:// 开头）时惰性读取：`get_config()` 下的 `channels.xiaoyi.file_upload_url`、`api_key`、`uid` 三项构成 `XiaoyiObsUploadConfig`。缺失 `file_upload_url` 或 `api_key` 会抛 RuntimeError；但 `uid` 先经 `str()` 转换再判断，缺失时变成字符串 "None" 而不会触发该报错。其余 intent 命令参数（如 timeOut=5、bundleName）为固定值，intentParam 内容由各工具入参派生。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py:L310–L330](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py#L310-L330)
+
+<!-- kb:knowledge owner=feature-xiaoyi-collection-tools facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证现状：无测试代码，仅运行时日志**
+
+本文件内无测试代码；docstring 声明与 xy_channel 的 TypeScript 工具（xiaoyi-collection-tool.ts 等）行为对齐，属文档性声明而非可执行验证。运行时可观测性有限：delete 仅记录规范化后的条目数量、add 仅记录 dataType，成功日志不含 outputs 内容；`ToolInputError` 被直接重抛，不产生失败日志。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py:L49–L49](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py#L49-L49), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py:L182–L185](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py#L182-L185), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py:L305–L308](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py#L305-L308), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py:L386–L387](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/xiaoyi_collection_tool.py#L386-L387)
+
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-contact-search.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-contact-search.md
new file mode 100644
index 00000000..93622b21
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-contact-search.md
@@ -0,0 +1,54 @@
+---
+title: "search_contact 设备联系人搜索工具（feature-xiaoyi-contact-search）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py:L45-L56, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py:L82-L95, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py:L56-L80, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py:L30-L47, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py:L93-L102, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py:L30-L36, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py:L64-L71, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py:L82-L96, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py:L45-L54, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py:L87-L102]
+feature: "xiaoyi-contact-search"
+entry_points: ["jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py"]
+source_globs: ["jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py"]
+---
+
+# search_contact 设备联系人搜索工具（feature-xiaoyi-contact-search）
+
+<!-- kb:knowledge owner=feature-xiaoyi-contact-search facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**职责边界与控制流**
+
+该工具是薄适配层：清洗输入（strip）后组装一条 Common/Action 设备命令，委托 `execute_device_command("SearchContactLocal", command)` 与设备侧调度服务通信，本身不持有通讯录数据。返回值做防御性归一化：非 dict 的 outputs 包装为 `{"outputs": outputs}`，非 dict 的 result 置空，再统计 `result["items"]` 条数用于日志与提示语。日志统一带 `[SEARCH_CONTACT_TOOL]` 前缀。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py:L45–L56](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py#L45-L56), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py:L82–L95](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py#L82-L95)
+
+<!-- kb:knowledge owner=feature-xiaoyi-contact-search facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**命令参数与固定设置**
+
+意图执行参数硬编码在 `executeParam` 中：`intentName: "SearchContactLocal"`、`bundleName: "com.huawei.hmos.aidispatchservice"`、`executeMode: "background"`、`needUnlock: True`、`actionResponse: True`、`appType: "OHOS_APP"`、`timeOut: 5`、`achieveType: "INTENT"`；检索词通过 `intentParam: {"name": name_clean}` 传入。这些值均为代码内常量，未见外部配置项或环境变量覆盖路径。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py:L56–L80](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py#L56-L80)
+
+<!-- kb:knowledge owner=feature-xiaoyi-contact-search facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**search_contact 入口契约**
+
+异步函数 `search_contact(name: str) -> Dict[str, Any]`，描述声明返回的 `content[0].text` 为设备 outputs 的 JSON 字符串。入口先校验参数：name 非字符串或去空白后为空时抛出 `ToolInputError("缺少必填参数 name")`；其余异常记录日志后包装为 `RuntimeError("搜索联系人失败: ...")`，而 `ToolInputError` 被原样上抛。工具描述中还向调用方声明 60 秒超时并提示最多重试一次。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py:L30–L47](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py#L30-L47), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py:L93–L102](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py#L93-L102)
+
+<!-- kb:knowledge owner=feature-xiaoyi-contact-search facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**按姓名检索设备联系人**
+
+按联系人姓名在设备通讯录中检索详细信息（描述称包括姓名、电话号码、邮箱、组织、职位等），实现方式是组装 Common/Action 命令并调用 `execute_device_command("SearchContactLocal", command)`，目标意图为 `SearchContactLocal`、bundle 为 `com.huawei.hmos.aidispatchservice`。返回前对结果做防御性归一化（非 dict 的 outputs 包装、非 dict 的 result 置空），统计 `result["items"]` 条数写入日志并体现在成功提示「搜索到联系人信息（N 条）」中。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py:L30–L36](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py#L30-L36), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py:L64–L71](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py#L64-L71), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py:L82–L96](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py#L82-L96)
+
+<!-- kb:knowledge owner=feature-xiaoyi-contact-search facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**Validation and Observability**
+
+The validation within the function is limited to input and exception contracts: it throws `ToolInputError` when `name` is not a string or is empty after trimming (L46–L47); when other exceptions occur, it logs an error and wraps them into `RuntimeError` before re-raising (L98–L102). At runtime, logs prefixed with `[SEARCH_CONTACT_TOOL]` record search terms and the number of items in the result (L51–L54, L91). No test cases or test entry points for `search_contact` appear within the source code slice provided this time; the existence of tests outside the slice cannot be confirmed or denied.
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py:L45–L54](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py#L45-L54), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py:L87–L102](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/contact_tools.py#L87-L102)
+
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-location-tool.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-location-tool.md
new file mode 100644
index 00000000..dc4b9996
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-location-tool.md
@@ -0,0 +1,56 @@
+---
+title: "设备定位工具 get_user_location（feature-xiaoyi-location-tool）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/location_tool.py:L19-L31, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/location_tool.py:L68-L86, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/location_tool.py:L33-L68, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/location_tool.py:L19-L26, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/location_tool.py:L41-L54, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/location_tool.py:L68-L73, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/location_tool.py:L67-L73]
+feature: "xiaoyi-location-tool"
+entry_points: ["jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/location_tool.py"]
+source_globs: ["jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/location_tool.py"]
+---
+
+# 设备定位工具 get_user_location（feature-xiaoyi-location-tool）
+
+<!-- kb:knowledge owner=feature-xiaoyi-location-tool facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**公共入口与返回契约**
+
+`get_user_location` 是一个用 `@tool` 装饰器注册的异步工具，名称为 `get_user_location`，无输入参数。工具描述声明返回 WGS84 经纬度坐标、需要设备授权位置权限，且操作超时 60 秒、失败后最多重试一次。返回值是工具标准响应结构：`content[0].text` 为设备 `outputs` 的 JSON 字符串（`ensure_ascii=False`）。非 dict 的 `outputs` 会被包成 `{"value": outputs}`；检测到设备错误时通过 `raise_if_device_error(outputs, "获取位置失败")` 抛出异常。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/location_tool.py:L19–L31](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/location_tool.py#L19-L31), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/location_tool.py:L68–L86](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/location_tool.py#L68-L86)
+
+<!-- kb:knowledge owner=feature-xiaoyi-location-tool facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**命令构造与设备执行流**
+
+工具自身不直接访问定位硬件，而是构造一个 `Common/Action` 协议命令并交给共享的 `execute_device_command("GetCurrentLocation", command)` 异步等待设备返回。命令的 `executeParam` 指向华为 HMOS 的意图派发服务（`bundleName: com.huawei.hmos.aidispatchservice`，`intentName: GetCurrentLocation`，`achieveType: INTENT`，`executeMode: background`，`needUnlock: True`，`timeOut: 5`），属于典型的代理/转发模式：定位能力由设备端实现，工具只做命令拼装、响应校验与格式化。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/location_tool.py:L33–L68](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/location_tool.py#L33-L68)
+
+<!-- kb:knowledge owner=feature-xiaoyi-location-tool facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**配置项与硬编码参数**
+
+工具无输入参数，所有命令参数均以字面量硬编码在函数体内：`bundleName: com.huawei.hmos.aidispatchservice`、`intentName: GetCurrentLocation`、`isNeedGeoAddress: True`、`timeOut: 5` 等。工具描述另声明面向调用方的操作超时为 60 秒、失败后最多重试一次；这两个数字分属不同层（提示语 vs 命令字段 `timeOut`），所示代码未说明 `timeOut: 5` 的单位与作用范围，也不含任何外部配置读取。改动这些行为需修改此文件代码。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/location_tool.py:L19–L26](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/location_tool.py#L19-L26), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/location_tool.py:L41–L54](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/location_tool.py#L41-L54)
+
+<!-- kb:knowledge owner=feature-xiaoyi-location-tool facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**设计取舍（推断）**
+
+Inference / 设计推断（非作者历史意图）：
+
+推断：工具选择零参数、全部协议字段硬编码的薄代理设计，换取调用简单与行为可预测，代价是坐标精度、超时单位、目标 bundle 等无法按调用调整。重试与节流不在工具内实现——函数体 L26–L86 未包含任何重试逻辑，而是把"60 秒超时、最多重试一次"写入面向调用模型的工具描述（L23），即由模型侧遵守；该约束的来源与理由无文档证据，标注为基于代码形态的推断。`execute_device_command` 的内部行为（如它自身的超时/重试）未在所示代码中体现。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/location_tool.py:L19–L26](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/location_tool.py#L19-L26), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/location_tool.py:L68–L73](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/location_tool.py#L68-L73)
+
+<!-- kb:knowledge owner=feature-xiaoyi-location-tool facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**功能行为**
+
+`get_user_location` 是注册名为 `get_user_location` 的零参数异步工具，声明返回用户当前位置的 WGS84 经纬度坐标，且需要设备授权位置访问权限；描述还要求调用方遵守 60 秒操作超时、失败后最多重试一次。功能实现上，它构造 `Common/Action` 协议命令（`intentName: GetCurrentLocation`、`bundleName: com.huawei.hmos.aidispatchservice`、`executeMode: background`），并通过 `intentParam.isNeedGeoAddress: True` 请求逆地理地址，随后交由共享的 `execute_device_command` 等待设备返回，定位能力本身由设备端服务提供。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/location_tool.py:L19–L26](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/location_tool.py#L19-L26), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/location_tool.py:L41–L54](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/location_tool.py#L41-L54), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/location_tool.py:L67–L73](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/location_tool.py#L67-L73)
+
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-note-tools.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-note-tools.md
new file mode 100644
index 00000000..9979fa6c
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-note-tools.md
@@ -0,0 +1,62 @@
+---
+title: "小艺备忘录工具（create_note / search_notes / modify_note）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L26-L51, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L93-L97, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L15-L23, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L54-L91, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L53-L80, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L126-L152, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L206-L234, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L100-L124, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L161-L167, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L176-L193, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L18-L23, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L179-L193, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L221-L225, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L236-L251, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L119-L124, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L243-L251]
+feature: "xiaoyi-note-tools"
+entry_points: ["jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py"]
+source_globs: ["jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py"]
+---
+
+# 小艺备忘录工具（create_note / search_notes / modify_note）
+
+<!-- kb:knowledge owner=feature-xiaoyi-note-tools facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**公开接口：三个异步备忘录工具**
+
+模块导出三个用 `@tool` 装饰的异步函数：`create_note(title: str, content: str)`、`search_notes(query: str)` 和 `modify_note(entity_id: str, text: str)`，均返回 `Dict[str, Any]`。参数校验失败时抛出 `ToolInputError`（如缺少 title/query/entity_id），其余异常统一包装为带中文上下文的 `RuntimeError`（如“创建备忘录失败: …”），且 `ToolInputError` 原样上抛不包装。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L26–L51](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py#L26-L51), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L93–L97](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py#L93-L97)
+
+<!-- kb:knowledge owner=feature-xiaoyi-note-tools facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**职责边界：参数校验 + 组装设备命令 + 结果包装**
+
+每个工具校验输入后组装一个 `header(namespace=Common, name=Action)` + `payload.executeParam` 的命令字典，通过共享的 `execute_device_command` 下发到设备，再用 `raise_if_device_error` 检查错误、`format_success_response` 包装设备完整 outputs 返回。工具本身不处理设备通信细节，边界清晰依赖 `utils` 模块的四个辅助件。三个命令分别对应 intentName `CreateNote` / `SearchNote` / `ModifyNote`，bundle 均为 `com.huawei.hmos.notepad`。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L15–L23](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py#L15-L23), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L54–L91](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py#L54-L91)
+
+<!-- kb:knowledge owner=feature-xiaoyi-note-tools facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**命令载荷中的固定参数**
+
+三个工具组装的设备命令中，除来自函数参数的 title/content/query/text/entityId 外，其余字段为固定值：executeMode="background"、needUnlock=True、actionResponse=True、timeOut=5、achieveType="INTENT"、bundleName="com.huawei.hmos.notepad"，header 固定为 namespace="Common"、name="Action"，没有外部配置入口或环境变量覆盖。create_note 与 search_notes 的 executeParam 不含 appType、permissionId 且带 dimension=""，而 modify_note 不含 dimension，但额外带 appType="OHOS_APP"、permissionId=[] 与 contentType="1"。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L53–L80](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py#L53-L80), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L126–L152](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py#L126-L152), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L206–L234](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py#L206-L234)
+
+<!-- kb:knowledge owner=feature-xiaoyi-note-tools facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的备忘录行为与调用纪律**
+
+create_note 需要必填的 title 与 content 创建备忘录；search_notes 接受关键词 query（去除首尾空白后不得为空）检索备忘录的标题、内容和附件名称，成功时统计设备 outputs 中 result.items 的条数并写入日志与提示语，返回包装后的完整 outputs。modify_note 为追加模式：必须先用 search_notes 取得备忘录的 entityId，再把 text 追加到该备忘录。三个工具的描述均约定操作超时时间 60 秒、失败最多重试一次、不可重复调用。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L100–L124](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py#L100-L124), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L161–L167](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py#L161-L167), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L176–L193](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py#L176-L193)
+
+<!-- kb:knowledge owner=feature-xiaoyi-note-tools facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**设计取舍：共享执行管线与追加式修改**
+
+三个工具复用同一执行管线：本地校验参数后组装命令字典，交给共享的 execute_device_command 下发，再统一用 raise_if_device_error 检查、format_success_response 包装返回；工具本身不实现设备通信，异常时除 ToolInputError 原样上抛外，其余异常经 logger.error 记录后包装为带中文上下文的 RuntimeError。取舍上，modify_note 选择追加模式而非任意编辑：调用方必须先经 search_notes 取得 entityId 才能定位目标备忘录，intentParam 仅携带 contentType/text/entityId 三个字段，简化了修改语义但限制了只能追加文本。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L18–L23](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py#L18-L23), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L179–L193](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py#L179-L193), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L221–L225](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py#L221-L225), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L236–L251](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py#L236-L251)
+
+<!-- kb:knowledge owner=feature-xiaoyi-note-tools facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证：运行时校验与日志观测点**
+
+所示代码中的验证是运行时输入校验：三个工具在组装命令前检查必填参数的存在与字符串类型，缺失即抛 ToolInputError（search_notes 还对 query 做 strip 后非空检查），该异常被 except 子句直接重新抛出、不包装。设备侧结果由 raise_if_device_error 统一判定错误。日志观测点：成功路径记录 create 完成、search 的 result.items 条数统计、modify 成功；失败路径仅在非 ToolInputError 异常分支用 logger.error 记录后再抛 RuntimeError。本片段未展示测试文件，无法据此判断测试覆盖情况。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L119–L124](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py#L119-L124), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L161–L167](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py#L161-L167), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py:L243–L251](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/note_tools.py#L243-L251)
+
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-photo-gallery-tools.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-photo-gallery-tools.md
new file mode 100644
index 00000000..7e3b6541
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-photo-gallery-tools.md
@@ -0,0 +1,54 @@
+---
+title: "小艺图库工具：search_photo_gallery / upload_photo (photo_tools.py)"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py:L62-L81, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py:L173-L195, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py:L263-L281, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py:L83-L116, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py:L203-L229, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py:L154-L156, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py:L88-L108, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py:L56-L60, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py:L30-L48, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py:L161-L171, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py:L111-L124, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py:L189-L199, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py:L229-L275, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py:L126-L130]
+feature: "xiaoyi-photo-gallery-tools"
+entry_points: ["jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py"]
+source_globs: ["jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py"]
+---
+
+# 小艺图库工具：search_photo_gallery / upload_photo (photo_tools.py)
+
+<!-- kb:knowledge owner=feature-xiaoyi-photo-gallery-tools facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**公开入口与输入输出契约**
+
+两个 async 工具通过 `@tool` 装饰器注册。`search_photo_gallery(query: str)` 要求非空字符串 query，返回设备 outputs 经 `format_success_response` 包装的结果并附带命中数量消息。`upload_photo(media_uris: Union[str, List[str]])` 接受 URI 数组或 JSON 数组字符串（空数组或超过 5 条抛 `ToolInputError`），成功时返回 `{content: [{type: "text", text: JSON}]}`，JSON 含 `imageUrls`、`count`、`message`。两者均把 `ToolInputError` 原样抛出、其余异常包装为 `RuntimeError`（含中文错误信息）。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py:L62–L81](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py#L62-L81), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py:L173–L195](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py#L173-L195), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py:L263–L281](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py#L263-L281)
+
+<!-- kb:knowledge owner=feature-xiaoyi-photo-gallery-tools facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**设备指令转发与数据流**
+
+两个工具都是设备指令的薄封装：构造 `Common/Action` 命令并通过共享的 `execute_device_command` 发给手机。搜索走 intent `SearchPhotoVideo`（bundle `com.huawei.hmos.aidispatchservice`），上传走 intent `ImageUploadForClaw`（bundle `com.huawei.hmos.vassistant`），均为 background 执行模式且 `needUnlock: True`。上传返回后从 `result.imageUrls` 提取 URL 并经 `_decode_image_url_escapes` 还原 `\u003d`/`\u0026` 转义（注释说明与 TypeScript 版 upload-photo-tool 的 getPhotoUrls 保持一致）。数据流是：搜索返回本地 mediaUri/thumbnailUri → 上传将其转为公网 URL。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py:L83–L116](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py#L83-L116), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py:L203–L229](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py#L203-L229), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py:L154–L156](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py#L154-L156)
+
+<!-- kb:knowledge owner=feature-xiaoyi-photo-gallery-tools facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**内嵌指令参数**
+
+模块没有用户可配置项；命令参数硬编码在函数体内：两次调用均设置 `executeMode: "background"`、`needUnlock: True`、`actionResponse: True`、`appType: "OHOS_APP"`、`timeOut: 5`、`achieveType: "INTENT"`、`needUploadResult: True`。工具描述声明面向调用方的操作超时为 60 秒且失败最多重试一次，但这属于提示词层面的约束，代码中并未实现重试逻辑。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py:L88–L108](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py#L88-L108), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py:L56–L60](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py#L56-L60)
+
+<!-- kb:knowledge owner=feature-xiaoyi-photo-gallery-tools facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的行为与能力边界**
+
+`search_photo_gallery(query)` 按自然语言描述检索手机本地（非云端）图库，返回照片的本地 `mediaUri`/`thumbnailUri`；工具描述要求优先使用 thumbnailUri 交给 `upload_photo` 换取公网 URL。描述声明支持口语化实体、相册名和人像（需人像 tag）检索；多实体/"或"逻辑及时间范围查询**必须**拆分成多次单实体查询（如"南京或上海"需分别查询），相对时间词（"最新""去年"）必须换算为具体年份，且需主动拆分并告知用户。`upload_photo(media_uris)` 把 `file://` 本地 URI（数组或 JSON 数组字符串，每次最多 5 条）上传并返回 `imageUrls`/`count`/`message`。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py:L30–L48](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py#L30-L48), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py:L56–L60](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py#L56-L60), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py:L161–L171](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py#L161-L171)
+
+<!-- kb:knowledge owner=feature-xiaoyi-photo-gallery-tools facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证路径**
+
+本文件内的可验证逻辑是输入校验与响应构造：`search_photo_gallery` 对缺失/空白 query 抛 `ToolInputError`（L76–L81），`upload_photo` 对空数组、超 5 条、非字符串元素抛 `ToolInputError`（L189–L199）。错误契约方面，两工具均将 `ToolInputError` 原样上抛、其余异常包装为中文 `RuntimeError`（L126–L130、L277–L281）。成功路径上两者使用共享助手的程度不同：搜索调用 `execute_device_command` 后经 `raise_if_device_error` 与 `format_success_response` 返回（L111–L124）；上传仅调用 `execute_device_command`，自行从 `result.imageUrls` 构造 JSON text 响应，不经 `raise_if_device_error`/`format_success_response`（L229–L275）。所示输入中没有该模块的测试文件。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py:L111–L124](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py#L111-L124), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py:L189–L199](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py#L189-L199), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py:L229–L275](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py#L229-L275), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py:L126–L130](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/photo_tools.py#L126-L130)
+
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-pushdata-store-and-viewer.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-pushdata-store-and-viewer.md
new file mode 100644
index 00000000..e8daa9ac
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-pushdata-store-and-viewer.md
@@ -0,0 +1,62 @@
+---
+title: "推送记录持久化与查询：pushdata_manager 与 view_push_result"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/pushdata_manager.py:L72-L100, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/push_result_tool.py:L36-L58, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/push_result_tool.py:L136-L152, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/pushdata_manager.py:L18-L25, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/pushdata_manager.py:L54-L66, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/push_result_tool.py:L49-L51, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/pushdata_manager.py:L103-L124, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/push_result_tool.py:L94-L108, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/pushdata_manager.py:L34-L51, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/push_result_tool.py:L64-L69, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/push_result_tool.py:L14-L18, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/push_result_tool.py:L49-L69, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/pushdata_manager.py:L54-L69, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/push_result_tool.py:L52-L69, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/push_result_tool.py:L136-L148]
+feature: "xiaoyi-pushdata-store-and-viewer"
+entry_points: ["jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/push_result_tool.py", "jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/pushdata_manager.py"]
+source_globs: ["jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/push_result_tool.py", "jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/pushdata_manager.py"]
+---
+
+# 推送记录持久化与查询：pushdata_manager 与 view_push_result
+
+<!-- kb:knowledge owner=feature-xiaoyi-pushdata-store-and-viewer facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**公开入口与返回契约**
+
+pushdata_manager 提供 save_push_data(data_detail) -> pushDataId（UUID 字符串）、search_push_data(keywords)、get_all_push_data() 与 clear_all_push_data()。push_result_tool 暴露 agent 工具 view_push_result(keywords, limit)，返回 content[0].text 为 JSON 字符串，含 success、count、items、message 字段；异常时捕获 Exception 返回 success:false 与 error 信息（查询本身不抛出）。工具层计算 effective_limit = min(limit or 10, 50)，负数 limit 不会被钳制，再经 results[:effective_limit] 截取。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/pushdata_manager.py:L72–L100](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/pushdata_manager.py#L72-L100), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/push_result_tool.py:L36–L58](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/push_result_tool.py#L36-L58), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/push_result_tool.py:L136–L152](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/push_result_tool.py#L136-L152)
+
+<!-- kb:knowledge owner=feature-xiaoyi-pushdata-store-and-viewer facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**内置常量与默认值**
+
+模块内固定两个常量，无外部配置入口：PUSHDATA_FILE 经 os.path.expanduser 展开为 ~/.openclaw/pushData.json，MAX_PUSHDATA_ITEMS = 1000。写入时以 items[-MAX_PUSHDATA_ITEMS:] 保留列表尾部（追加发生在尾部，故保留的是最近写入的条目，依据是位置而非时间排序），仅当输入超过 1000 条时才记录裁剪日志。时间戳格式为北京时间 YYYYMMDD HHmmss。工具层默认返回 10 条（limit or 10）。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/pushdata_manager.py:L18–L25](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/pushdata_manager.py#L18-L25), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/pushdata_manager.py:L54–L66](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/pushdata_manager.py#L54-L66), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/push_result_tool.py:L49–L51](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/push_result_tool.py#L49-L51)
+
+<!-- kb:knowledge owner=feature-xiaoyi-pushdata-store-and-viewer facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的行为**
+
+关键词搜索为大小写不敏感的子串匹配，字段限定为 dataDetail 与 pushDataId；keywords 为 None 或空白时 search_push_data 返回全部条目，view_push_result 无关键词时走全量查询并按 effective_limit 截取（默认 10）。返回条目包含 pushDataId 前 8 位、完整 ID、time、dataDetail（超过 200 字符截断后追加 "..."，实际最长 203 字符）和 fullLength。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/pushdata_manager.py:L103–L124](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/pushdata_manager.py#L103-L124), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/push_result_tool.py:L94–L108](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/push_result_tool.py#L94-L108)
+
+<!-- kb:knowledge owner=feature-xiaoyi-pushdata-store-and-viewer facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**JSON 文件存储的取舍**
+
+采用单文件 JSON 而非数据库，实现简单、可直接人工查看，且读取端对 JSON 解析失败、非数组内容和 OSError 均降级为返回空列表并记日志，使文件缺失或整体损坏不致读取崩溃。代价是每次 save 全量重写文件、容量受 1000 条截断限制；读取端仅校验外层是列表，不校验条目结构，畸形条目（如 [null]）会透传，view_push_result 中对每条调用 .get() 时可能抛出并落入 success:false 分支。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/pushdata_manager.py:L34–L51](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/pushdata_manager.py#L34-L51), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/push_result_tool.py:L64–L69](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/push_result_tool.py#L64-L69)
+
+<!-- kb:knowledge owner=feature-xiaoyi-pushdata-store-and-viewer facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**两层结构：持久化模块与工具层**
+
+功能分两层。pushdata_manager.py 负责持久化：save_push_data 生成 UUID、以北京时间 YYYYMMDD HHmmss 为 time 组装条目，读出 ~/.openclaw/pushData.json 全量列表、追加后整体重写（写入时以 items[-1000:] 截断）。push_result_tool.py 是面向 agent 的工具层：通过 openjiuwen.core.foundation.tool 的 @tool 装饰器注册 view_push_result，按是否有关键词选择调用 search_push_data 或 get_all_push_data，按 time 字符串倒序排序后截取条数，把结果序列化为 JSON 文本放入 content[0].text 返回。两文件均为所示范围，未见其他模块调用。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/pushdata_manager.py:L72–L100](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/pushdata_manager.py#L72-L100), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/push_result_tool.py:L14–L18](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/push_result_tool.py#L14-L18), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/push_result_tool.py:L49–L69](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/push_result_tool.py#L49-L69)
+
+<!-- kb:knowledge owner=feature-xiaoyi-pushdata-store-and-viewer facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证手段：日志输出**
+
+所示两个文件不含测试代码。执行路径上的验证手段是 logger 输出：pushdata_manager 在保存（id 前 8 位、time、detail 长度）、裁剪（trim 前后条数）、搜索命中数和清空时打 INFO 日志；push_result_tool 记录查询入参、数据源返回条数与查询方式、截取后条数，异常时打 ERROR 日志。读取失败（JSON 解析错误、OSError）记录 ERROR 并降级返回空列表。这些是格式化文本日志，所示输入中未提供以它们断言的自动化测试入口。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/pushdata_manager.py:L54–L69](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/pushdata_manager.py#L54-L69), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/push_result_tool.py:L52–L69](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/push_result_tool.py#L52-L69), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/push_result_tool.py:L136–L148](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/push_result_tool.py#L136-L148)
+
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-save-to-phone-tools.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-save-to-phone-tools.md
new file mode 100644
index 00000000..2600ce72
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-save-to-phone-tools.md
@@ -0,0 +1,46 @@
+---
+title: "小艺保存到手机工具（save_media_to_gallery / save_file_to_file_manager）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/save_tools.py:L43-L54, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/file_upload_helpers.py:L51-L59, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/save_tools.py:L21-L26, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/save_tools.py:L102-L146, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/save_tools.py:L227-L255, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/save_tools.py:L164-L168, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/file_upload_helpers.py:L60-L67, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/file_upload_helpers.py:L74-L81, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/file_upload_helpers.py:L85-L92, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/save_tools.py:L29-L40, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/file_upload_helpers.py:L25-L59, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/file_upload_helpers.py:L74-L92]
+feature: "xiaoyi-save-to-phone-tools"
+entry_points: ["jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/save_tools.py"]
+source_globs: ["jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/save_tools.py", "jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/file_upload_helpers.py"]
+---
+
+# 小艺保存到手机工具（save_media_to_gallery / save_file_to_file_manager）
+
+<!-- kb:knowledge owner=feature-xiaoyi-save-to-phone-tools facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**channels.xiaoyi 上传配置**
+
+工具从全局配置的 `channels.xiaoyi` 读取三个键：`file_upload_url`（OBS 服务 base_url）、`api_key`、`uid`，用于构造 `XiaoyiObsUploadConfig`。base_url 和 api_key 缺失（或 uid 缺失）时抛 `ToolInputError`；注意 `uid` 经 `str(xc.get("uid"))` 转换，缺失时变成真值字符串 `"None"`，因此缺失的 uid 实际不会触发该错误。请求侧将 uid 同时用作 header（`x-uid`）和 `fileOwnerInfo` 的 `uid`/`teamId`，api_key 走 `x-api-key`，并固定附带 `x-request-from: openclaw`。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/save_tools.py:L43–L54](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/save_tools.py#L43-L54), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/file_upload_helpers.py:L51–L59](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/file_upload_helpers.py#L51-L59)
+
+<!-- kb:knowledge owner=feature-xiaoyi-save-to-phone-tools facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**命令组装与执行流程**
+
+工具在 save_tools.py 内直接完成参数校验、本地文件上传换公网 URL（`_ensure_public_url` 通过 aiohttp 会话调用 `upload_local_file_public_url`）以及设备命令字典的组装，随后交给共享 `.utils` 的 `execute_device_command` 执行并用 `raise_if_device_error` 检查结果。两个命令均为 Common/Action 事件：图库用 intentName `SaveMediaToGallery`，文件管理器用 `SaveFileToFileManager`，bundleName 都是 `com.huawei.hmos.vassistant`，executeMode 为 background，permissionId 含 `ohos.permission.WRITE_IMAGEVIDEO`。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/save_tools.py:L21–L26](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/save_tools.py#L21-L26), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/save_tools.py:L102–L146](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/save_tools.py#L102-L146), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/save_tools.py:L227–L255](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/save_tools.py#L227-L255)
+
+<!-- kb:knowledge owner=feature-xiaoyi-save-to-phone-tools facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**输入校验与错误处理路径**
+
+工具入口对必填参数与 media_type 枚举做显式校验并抛 ToolInputError；该异常在两个工具的兜底 except 中被原样 re-raise，不记日志也不包装。上传侧的分阶段检查不对称：prepare 除 HTTP 状态外还校验业务码 `code != "0"`，文件上传仅检查 HTTP 状态，completeAndQuery 检查 HTTP 状态且要求返回 `fileDetailInfo.url` 非空，否则抛 RuntimeError。设备执行结果经 `raise_if_device_error` 检查（其实现位于未展示的 .utils 中）。本次输入不含任何测试文件。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/save_tools.py:L164–L168](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/save_tools.py#L164-L168), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/file_upload_helpers.py:L60–L67](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/file_upload_helpers.py#L60-L67), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/file_upload_helpers.py:L74–L81](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/file_upload_helpers.py#L74-L81), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/file_upload_helpers.py:L85–L92](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/file_upload_helpers.py#L85-L92)
+
+<!-- kb:knowledge owner=feature-xiaoyi-save-to-phone-tools facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**本地文件上传换公网 URL 的三段式 OBS 流程**
+
+当 url 不是 `http://`/`https://` 开头时，工具将其视为本地路径，通过 `upload_local_file_public_url` 上传：先同步读入整个文件并计算 SHA-256，POST `{base}/osms/v1/file/manager/prepare`（携带 `x-uid`、`x-api-key`、`x-request-from: openclaw` 头，校验业务码 `code == "0"`），再按 prepare 返回的 `uploadInfos[0]` 的 method（缺省 PUT）、url 和服务端给的 headers 上传文件内容，最后 POST `completeAndQuery` 并要求返回 `fileDetailInfo.url` 非空；任一步失败抛 RuntimeError。已是 http(s) 的 URL 则直接透传，跳过上传。objectType 固定为 `TEMPORARY_MATERIAL_DOC`。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/save_tools.py:L29–L40](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/save_tools.py#L29-L40), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/file_upload_helpers.py:L25–L59](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/file_upload_helpers.py#L25-L59), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/file_upload_helpers.py:L74–L92](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/file_upload_helpers.py#L74-L92)
+
diff --git a/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-timestamp-utc8-tool.md b/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-timestamp-utc8-tool.md
new file mode 100644
index 00000000..3f37037f
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/agents-team/feature-xiaoyi-timestamp-utc8-tool.md
@@ -0,0 +1,64 @@
+---
+title: "时间戳转北京时间工具 (convert_timestamp_to_utc8_time)"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py:L37-L60, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py:L39-L47, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py:L71-L75, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py:L13-L16, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py:L49-L69, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py:L71-L84, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py:L49-L63, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py:L69-L69, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py:L19-L43, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py:L62-L84, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py:L29-L35, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py:L49-L65]
+feature: "xiaoyi-timestamp-utc8-tool"
+entry_points: ["jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py"]
+source_globs: ["jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py"]
+---
+
+# 时间戳转北京时间工具 (convert_timestamp_to_utc8_time)
+
+<!-- kb:knowledge owner=feature-xiaoyi-timestamp-utc8-tool facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**设计取舍**
+
+Inference / 设计推断（非作者历史意图）：
+
+秒/毫秒判别采用混合启发式：先按十进制字符串长度（13 或 10）匹配，再用 `> 1e12` 阈值兜底，其余一律按秒处理。这换来对常见输入的鲁棒性，但边界值（如 11–12 位或极小的毫秒时间戳）会被误判为秒级——属于推断的代价，所示代码未附作者说明。函数签名标注 `float` 却同时接受 int，NaN/Inf 显式拒绝，是防御性校验的选择。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py:L37–L60](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py#L37-L60)
+
+<!-- kb:knowledge owner=feature-xiaoyi-timestamp-utc8-tool facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证入口**
+
+所示文件中不含测试代码；工具内的运行时校验（None 检查、类型检查、NaN/Inf 检查、`fromtimestamp` 的异常捕获）构成输入层面的防御，成功转换会通过 `logger.info("[TIMESTAMP_TOOL] ...")` 留下可观测日志。未在本次提供的材料中看到针对该工具的测试文件，无法断言其覆盖情况。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py:L39–L47](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py#L39-L47), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py:L71–L75](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py#L71-L75)
+
+<!-- kb:knowledge owner=feature-xiaoyi-timestamp-utc8-tool facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**职责与数据流**
+
+该工具位于 `xiaoyi_phone_tools` 包内，依赖 `openjiuwen.core.foundation.tool` 的 `@tool` 装饰器完成注册，复用包内 `utils.ToolInputError` 和 `jiuwenswarm.common.utils.logger`。执行流程为：输入校验（None/类型/NaN/Inf）→ 秒/毫秒判别（按绝对值取整后的十进制字符串长度 13 或 10，`abs > 1e12` 兜底为毫秒，其余按秒乘 1000）→ 用固定 UTC+8 时区 `datetime.fromtimestamp` 转换 → `strftime("%Y%m%d %H%M%S")` 格式化。它不是纯函数：成功转换会执行 `logger.info("[TIMESTAMP_TOOL] ...")` 产生可观测的日志副作用，然后再返回结果字典。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py:L13–L16](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py#L13-L16), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py:L49–L69](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py#L49-L69), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py:L71–L84](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py#L71-L84)
+
+<!-- kb:knowledge owner=feature-xiaoyi-timestamp-utc8-tool facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**固定行为参数**
+
+工具没有可配置项：时区硬编码为 `timezone(timedelta(hours=8))`，输出格式硬编码为 `%Y%m%d %H%M%S`。秒/毫秒判别的启发式也是编译在代码里的常量：对绝对值 `ts_abs = abs(timestamp)` 取整后转字符串，长度为 13 按毫秒、为 10 按秒，`ts_abs > 1000000000000` 也按毫秒，其余一律按秒（乘 1000）。注意阈值比较的是绝对值，例如绝对值超过 1e12 的负数时间戳同样按毫秒处理。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py:L49–L63](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py#L49-L63), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py:L69–L69](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py#L69-L69)
+
+<!-- kb:knowledge owner=feature-xiaoyi-timestamp-utc8-tool facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**公开入口与输入输出契约**
+
+公开入口是经 `@tool` 装饰器注册的 `convert_timestamp_to_utc8_time(timestamp: float) -> dict`，工具名为 `convert_timestamp_to_utc8_time`，描述中声明接受秒级（10 位）或毫秒级（13 位）数字时间戳。输入契约：None、非 int/float 类型、NaN/Inf 均抛出 `ToolInputError`（中文错误消息）；`datetime.fromtimestamp` 转换失败时同样包装为 `ToolInputError`。输出为 `dict`，形如 `{"content": [{"type": "text", "text": "YYYYMMDD hhmmss"}]}`，格式由 `strftime("%Y%m%d %H%M%S")` 硬编码为 UTC+8 时间。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py:L19–L43](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py#L19-L43), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py:L62–L84](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py#L62-L84)
+
+<!-- kb:knowledge owner=feature-xiaoyi-timestamp-utc8-tool facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持行为与依赖关系**
+
+核心行为：自动判别秒/毫秒时间戳——对绝对值取整后的十进制字符串长度为 13 按毫秒、为 10 按秒，绝对值大于 1e12 也按毫秒，其余按秒乘 1000；随后用固定时区 `timezone(timedelta(hours=8))` 转换为北京时间。依赖：`openjiuwen.core.foundation.tool` 的 `@tool` 装饰器、包内 `utils.ToolInputError`、`jiuwenswarm.common.utils.logger`（成功转换时记录 `[TIMESTAMP_TOOL]` 日志）。工具描述明确其与日程/闹钟搜索工具的关系：当 `search_calendar_event`、`search_alarm` 返回结果含时间戳时，建议优先调用本工具转换为标准北京时间再做回答。
+
+Sources / 来源：[jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py:L13–L16](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py#L13-L16), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py:L29–L35](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py#L29-L35), [jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py:L49–L65](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/tools/xiaoyi_phone_tools/timestamp_tool.py#L49-L65)
+
diff --git a/knowledge/repos/jiuwenswarm/components/auto-harness/feature-auto-harness.md b/knowledge/repos/jiuwenswarm/components/auto-harness/feature-auto-harness.md
index 02739abd..1acfbb41 100644
--- a/knowledge/repos/jiuwenswarm/components/auto-harness/feature-auto-harness.md
+++ b/knowledge/repos/jiuwenswarm/components/auto-harness/feature-auto-harness.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/AutoHarness.md
 feature: "auto-harness"
 entry_points: ["jiuwenswarm/agents/harness/common/auto_harness/service.py"]
-source_globs: ["jiuwenswarm/agents/harness/common/auto_harness/service.py", "jiuwenswarm/agents/harness/common/auto_harness/*"]
+source_globs: ["jiuwenswarm/agents/harness/common/auto_harness/service.py", "jiuwenswarm/agents/harness/common/auto_harness/*", "jiuwenswarm/server/agent_ws_server.py", "jiuwenswarm/agents/harness/common/auto_harness/capabilities.py", "jiuwenswarm/agents/harness/common/auto_harness/issue_fix/__init__.py", "jiuwenswarm/common/config_panel/tui_models_handlers.py", "jiuwenswarm/agents/harness/common/auto_harness/config_validator.py", "jiuwenswarm/agents/harness/common/auto_harness/__init__.py", "jiuwenswarm/agents/harness/common/auto_harness/run_log_status.py", "jiuwenswarm/agents/harness/common/auto_harness/scheduler.py", "jiuwenswarm/server/runtime/agent_adapter/interface_deep.py", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/auto-harness.ts", "jiuwenswarm/agents/harness/common/rsi/materializer.py", "jiuwenswarm/agents/harness/common/auto_harness/repo_auth/__init__.py", "jiuwenswarm/agents/harness/common/auto_harness/repo_auth/gitcode.py", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ChatPanel.css", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/HarnessProgressBar.tsx", "jiuwenswarm/agents/harness/common/auto_harness/issue_fix/run_progress.py", "jiuwenswarm/agents/harness/common/auto_harness/issue_fix/service.py", "jiuwenswarm/agents/harness/common/auto_harness/issue_fix/issue_matrix_store.py", "jiuwenswarm/channels/web/frontend/src/components/ToolPanel/ReadOnlyFileModal.tsx", "jiuwenswarm/channels/web/frontend/src/features/rsi/components/RsiCanvasArea.tsx", "jiuwenswarm/agents/harness/common/rsi/models.py", "jiuwenswarm/agents/harness/common/rsi/adapter.py", "jiuwenswarm/agents/harness/common/rsi/event_consumer.py", "jiuwenswarm/agents/harness/common/rsi/events.py", "jiuwenswarm/agents/harness/common/rsi/errors.py", "jiuwenswarm/agents/harness/common/rsi/event_journal.py", "jiuwenswarm/agents/harness/common/rsi/harness_adapter.py", "jiuwenswarm/agents/harness/common/rsi/harness_provider.py", "jiuwenswarm/agents/harness/common/rsi/mock_harness_provider.py", "jiuwenswarm/agents/harness/common/rsi/provider_factory.py", "jiuwenswarm/agents/harness/common/rsi/services.py", "jiuwenswarm/channels/web/frontend/src/features/rsi/components/RsiResultSummary.tsx", "jiuwenswarm/agents/harness/common/rsi/context.py", "jiuwenswarm/agents/harness/common/rsi/__init__.py", "jiuwenswarm/channels/web/frontend/src/features/rsi/rsiPresentation.ts", "jiuwenswarm/channels/web/frontend/src/features/rsi/rsiApi.ts", "jiuwenswarm/channels/web/frontend/src/features/rsi/rsiTreeLayout.ts", "jiuwenswarm/agents/harness/common/rsi/paper_provider.py", "jiuwenswarm/agents/harness/common/rsi/usage_recorder.py", "jiuwenswarm/agents/harness/common/rsi/validation_dataset.py", "jiuwenswarm/agents/harness/common/rsi/worker.py", "jiuwenswarm/agents/harness/common/rsi/recovery.py", "jiuwenswarm/agents/harness/common/auto_harness/task_store.py", "jiuwenswarm/channels/web/frontend/src/stores/harnessStore.ts"]
 ---
 
 # Auto Harness 评测优化 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/auto-harness/feature-rsi-packages.md b/knowledge/repos/jiuwenswarm/components/auto-harness/feature-rsi-packages.md
index 7f62db7f..ba852808 100644
--- a/knowledge/repos/jiuwenswarm/components/auto-harness/feature-rsi-packages.md
+++ b/knowledge/repos/jiuwenswarm/components/auto-harness/feature-rsi-packages.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/AutoHarness.md
 feature: "rsi-packages"
 entry_points: ["jiuwenswarm/agents/harness/common/rsi/harness_activation.py"]
-source_globs: ["jiuwenswarm/agents/harness/common/rsi/harness_activation.py", "jiuwenswarm/agents/harness/common/rsi/*"]
+source_globs: ["jiuwenswarm/agents/harness/common/rsi/harness_activation.py", "jiuwenswarm/agents/harness/common/rsi/*", "jiuwenswarm/agents/harness/common/auto_harness/service.py", "jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py", "jiuwenswarm/agents/harness/common/rsi/plugin_catalog.py", "jiuwenswarm/channels/web/frontend/src/features/rsi/rsiApi.ts"]
 ---
 
 # Harness Package 与热激活 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/browser-client/_index.md b/knowledge/repos/jiuwenswarm/components/browser-client/_index.md
index c2be3031..16c52ba3 100644
--- a/knowledge/repos/jiuwenswarm/components/browser-client/_index.md
+++ b/knowledge/repos/jiuwenswarm/components/browser-client/_index.md
@@ -29,3 +29,6 @@ sources: []
 | PR 描述在做什么 | 精确规则 | 第一批 live 源码 |
 |---|---|---|
 | browser client | 入口 | `jiuwenswarm/channels/browser/frontend/src/background/index.ts`、`jiuwenswarm/channels/browser/frontend/src/sidepanel/index.ts`、`jiuwenswarm/channels/browser/` |
+
+- [JiuwenSwarm browser-client（Chromium 扩展）背景服务与内容脚本](knowledge.md)
+- [browser-client 源码接口与集成边界 01](source-contracts-01.md)
diff --git a/knowledge/repos/jiuwenswarm/components/browser-client/feature-browser-client.md b/knowledge/repos/jiuwenswarm/components/browser-client/feature-browser-client.md
index 4238a746..682eb8fc 100644
--- a/knowledge/repos/jiuwenswarm/components/browser-client/feature-browser-client.md
+++ b/knowledge/repos/jiuwenswarm/components/browser-client/feature-browser-client.md
@@ -11,7 +11,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/browser-extension/浏览器扩展.md
 feature: "browser-client"
 entry_points: ["jiuwenswarm/channels/browser/frontend/src/background/index.ts", "jiuwenswarm/channels/browser/frontend/src/sidepanel/index.ts"]
-source_globs: ["jiuwenswarm/channels/browser/frontend/src/background/index.ts", "jiuwenswarm/channels/browser/frontend/src/sidepanel/index.ts", "jiuwenswarm/channels/browser/frontend/src/*"]
+source_globs: ["jiuwenswarm/channels/browser/frontend/src/background/index.ts", "jiuwenswarm/channels/browser/frontend/src/sidepanel/index.ts", "jiuwenswarm/channels/browser/frontend/src/*", "jiuwenswarm/channels/browser/frontend/src/sidepanel/reader.ts", "jiuwenswarm/channels/browser/frontend/src/background/ToolDispatcher.ts", "jiuwenswarm/channels/browser/frontend/src/content/index.ts", "jiuwenswarm/channels/browser/frontend/src/content/Annotator.ts", "jiuwenswarm/channels/browser/frontend/src/content/FormAssist.ts", "jiuwenswarm/channels/browser/frontend/src/content/SelectionMonitor.ts", "jiuwenswarm/channels/browser/frontend/src/background/ContextMenu.ts", "jiuwenswarm/channels/browser/frontend/src/background/PanelManager.ts", "jiuwenswarm/channels/browser/frontend/src/shared/constants.ts", "jiuwenswarm/channels/browser/frontend/src/shared/types.ts", "jiuwenswarm/channels/browser/frontend/src/shared/url.ts", "jiuwenswarm/channels/browser/frontend/src/shared/i18n.ts", "jiuwenswarm/channels/browser/frontend/src/shared/logger.ts", "jiuwenswarm/channels/browser/frontend/src/background/WsClient.ts", "jiuwenswarm/channels/browser/frontend/src/shared/protocol.ts", "jiuwenswarm/channels/browser/frontend/src/shared/messages.ts", "jiuwenswarm/channels/browser/frontend/src/shared/storage.ts", "jiuwenswarm/channels/browser/frontend/src/options/index.ts", "jiuwenswarm/channels/browser/frontend/src/options/options.html", "jiuwenswarm/channels/browser/frontend/src/content/adapters/twitter.ts", "jiuwenswarm/channels/browser/frontend/src/content/adapters/wikipedia.ts", "jiuwenswarm/channels/browser/frontend/src/content/adapters/youtube.ts", "jiuwenswarm/channels/browser/frontend/src/background/ContextCache.ts", "jiuwenswarm/channels/browser/frontend/src/content/Extractor.ts", "jiuwenswarm/channels/browser/frontend/src/content/PageTypeDetector.ts", "jiuwenswarm/channels/browser/frontend/src/popup/index.ts", "jiuwenswarm/channels/browser/frontend/src/popup/popup.html", "jiuwenswarm/channels/browser/frontend/src/sidepanel/SessionExporter.ts", "jiuwenswarm/channels/browser/frontend/src/background/TabWatcher.ts", "jiuwenswarm/channels/browser/frontend/src/sidepanel/search.ts", "jiuwenswarm/channels/browser/frontend/src/sidepanel/ChatBridge.ts", "jiuwenswarm/channels/browser/frontend/src/sidepanel/chat.ts", "jiuwenswarm/channels/browser/frontend/src/sidepanel/ContextBar.ts", "jiuwenswarm/channels/browser/frontend/src/sidepanel/tour.ts", "jiuwenswarm/channels/browser/frontend/src/sidepanel/privacy.ts", "jiuwenswarm/channels/browser/frontend/src/sidepanel/sidepanel.html", "jiuwenswarm/channels/browser/frontend/src/sidepanel/markdown.ts", "jiuwenswarm/channels/browser/frontend/src/sidepanel/SessionPicker.ts", "jiuwenswarm/channels/browser/frontend/src/webview/chat.html"]
 ---
 
 # Chromium 浏览器扩展 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/browser-client/knowledge.md b/knowledge/repos/jiuwenswarm/components/browser-client/knowledge.md
new file mode 100644
index 00000000..bbe5cbf7
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/browser-client/knowledge.md
@@ -0,0 +1,43 @@
+---
+title: "JiuwenSwarm browser-client（Chromium 扩展）背景服务与内容脚本"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/browser/frontend/src/background/index.ts:L1-L13, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/browser/frontend/src/background/index.ts:L70-L93, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/browser/frontend/src/background/ToolDispatcher.ts:L48-L104, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/browser/frontend/src/background/WsClient.ts:L89-L99, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/browser/frontend/src/content/Extractor.ts:L33-L56, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/browser/frontend/src/background/ContextMenu.ts:L91-L111, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/browser/frontend/eslint.config.js:L3-L13, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/browser/frontend/scripts/pack.js:L19-L29, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/browser/frontend/scripts/pack.js:L44-L48]
+---
+
+# JiuwenSwarm browser-client（Chromium 扩展）背景服务与内容脚本
+
+<!-- kb:knowledge owner=browser-client facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**职责与数据流**
+
+background service worker 是扩展的中枢：维护到本地 JiuwenSwarm 服务器的 WebSocket 连接（gateway JSON-RPC，channel_id "browser"），管理研究会话、缓存页面上下文、注册右键菜单、监听标签页生命周期，并把服务器侧 agent 的 tool_call 信封分发给浏览器原生工具。各模块（WsClient、SessionManager、ContextCache、TabWatcher、ContextMenu、ToolDispatcher）作为单例在入口装配，入站事件按 ack / tool_call / 流式信封三类路由：ack 采纳会话，tool_call 进 ToolDispatcher，其余直接广播到侧栏端口。
+
+Sources / 来源：[jiuwenswarm/channels/browser/frontend/src/background/index.ts:L1–L13](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/browser/frontend/src/background/index.ts#L1-L13), [jiuwenswarm/channels/browser/frontend/src/background/index.ts:L70–L93](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/browser/frontend/src/background/index.ts#L70-L93)
+
+<!-- kb:knowledge owner=browser-client facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**ToolDispatcher 的工具调用契约**
+
+ToolDispatcher.dispatch 接收服务器下发的 tool_call 信封（payload 含 tool/args/call_id），在 switch 内执行八个浏览器工具；执行体的异常被 try/catch 捕获并转为 {error: String(e)} 作为结果（L57-L96）。但 payload 解构与 onTool 回调位于 try 之前（L49-L55），该处抛出的异常会绕过结果发送；且结果经 client.send 发送，WsClient.send 在未连接时记录警告并返回 null（丢弃），不保证送达。
+
+Sources / 来源：[jiuwenswarm/channels/browser/frontend/src/background/ToolDispatcher.ts:L48–L104](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/browser/frontend/src/background/ToolDispatcher.ts#L48-L104), [jiuwenswarm/channels/browser/frontend/src/background/WsClient.ts:L89–L99](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/browser/frontend/src/background/WsClient.ts#L89-L99)
+
+<!-- kb:knowledge owner=browser-client facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**页面适配器与上下文菜单行为**
+
+Extractor 按检测到的 pageType 分发到八个结构化适配器（github、arxiv、sec、pubmed、wikipedia、youtube、twitter、hackernews），其余走 Readability 兜底；pdf 类型不经适配器，直接返回提示需服务端 read_pdf 工具的 stub 上下文。右键菜单注册 ask/search/summarize/reader/pin 等项，其中 Pin 项标题仅在 onShown 检测到当前 URL 已被固定时更新为 "Unpin this page"（onShown/update 不可用时保持静态标题，切换仍经点击处理完成）。
+
+Sources / 来源：[jiuwenswarm/channels/browser/frontend/src/content/Extractor.ts:L33–L56](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/browser/frontend/src/content/Extractor.ts#L33-L56), [jiuwenswarm/channels/browser/frontend/src/background/ContextMenu.ts:L91–L111](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/browser/frontend/src/background/ContextMenu.ts#L91-L111)
+
+<!-- kb:knowledge owner=browser-client facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**工程级校验与打包入口**
+
+eslint.config.js 基于 typescript-eslint recommended，忽略 dist/、node_modules/、src/webview/，并将 no-explicit-any 与 no-unused-vars（argsIgnorePattern ^_）设为 warn 级提示。scripts/pack.js 在打包阶段校验构建产物存在：dist/ 缺失时报错并以退出码 1 终止（提示先 npm run build），否则将 dist/ 以 zip 压缩级别 9 归档为 jiuwenswarm-browser-<version>.zip 并输出体积日志。所列输入不含扩展运行时的测试文件。
+
+Sources / 来源：[jiuwenswarm/channels/browser/frontend/eslint.config.js:L3–L13](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/browser/frontend/eslint.config.js#L3-L13), [jiuwenswarm/channels/browser/frontend/scripts/pack.js:L19–L29](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/browser/frontend/scripts/pack.js#L19-L29), [jiuwenswarm/channels/browser/frontend/scripts/pack.js:L44–L48](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/browser/frontend/scripts/pack.js#L44-L48)
+
diff --git a/knowledge/repos/jiuwenswarm/components/browser-client/source-contracts-01.md b/knowledge/repos/jiuwenswarm/components/browser-client/source-contracts-01.md
new file mode 100644
index 00000000..83443d4d
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/browser-client/source-contracts-01.md
@@ -0,0 +1,28 @@
+---
+title: "browser-client 源码接口与集成边界 01"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: []
+---
+
+# browser-client 源码接口与集成边界 01
+
+本页逐文件说明这一源码模块声明的接口、类型与依赖。记录来自静态源码声明，不证明控制流、配置生效、外部服务可用或测试通过；功能语义与设计取舍沿上级功能页继续阅读。
+
+<!-- kb:file path=jiuwenswarm/channels/browser/frontend/vite.config.ts pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b sha256=c472d80b8a57a6c1321560f9698bc0d3b53dcbd6dfbda14e7ba3ce7747ea6b95 -->
+**`jiuwenswarm/channels/browser/frontend/vite.config.ts`**
+
+- 集成边界的导入/加载声明：`import { defineConfig } from "vite"`；`import { resolve } from "path"`；`import { cpSync, mkdirSync } from "fs"`。
+
+源码依据：[完整声明与实现](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/browser/frontend/vite.config.ts#L1-L54)。
+<!-- /kb:file -->
+
+<!-- kb:file path=jiuwenswarm/channels/browser/frontend/vite.content.config.ts pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b sha256=cf21833d47e98774e49688a556436779b488b04d748708b3b68e37d1093f0144 -->
+**`jiuwenswarm/channels/browser/frontend/vite.content.config.ts`**
+
+- 集成边界的导入/加载声明：`import { defineConfig } from "vite"`；`import { resolve } from "path"`。
+
+源码依据：[完整声明与实现](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/browser/frontend/vite.content.config.ts#L1-L35)。
+<!-- /kb:file -->
diff --git a/knowledge/repos/jiuwenswarm/components/common-core/feature-external-cli-agents.md b/knowledge/repos/jiuwenswarm/components/common-core/feature-external-cli-agents.md
index b0adfb35..ce1dfaca 100644
--- a/knowledge/repos/jiuwenswarm/components/common-core/feature-external-cli-agents.md
+++ b/knowledge/repos/jiuwenswarm/components/common-core/feature-external-cli-agents.md
@@ -11,7 +11,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/设置与频道升级迁移指南.md
 feature: "external-cli-agents"
 entry_points: ["jiuwenswarm/common/external_cli_runtime.py", "jiuwenswarm/common/external_cli_catalog.py"]
-source_globs: ["jiuwenswarm/common/external_cli_runtime.py", "jiuwenswarm/common/external_cli_catalog.py"]
+source_globs: ["jiuwenswarm/common/external_cli_runtime.py", "jiuwenswarm/common/external_cli_catalog.py", "jiuwenswarm/common/config_panel/config_set_handlers.py", "jiuwenswarm/common/config.py", "jiuwenswarm/extensions/agentos/agentos_router/router_client.py", "jiuwenswarm/channels/web/frontend/src/components/ExternalCliAgentsSection.tsx", "jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py", "jiuwenswarm/channels/web/frontend/src/components/ExternalCliInstallDialog.css", "jiuwenswarm/channels/web/frontend/src/components/ExternalCliInstallDialog.tsx", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/experimental/ExperimentalSettings.tsx", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/experimental/externalCliInstallState.ts", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/experimental/definition.ts", "jiuwenswarm/gateway/channel_manager/tui/tui_connect.py", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/switch.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/registry.ts", "jiuwenswarm/channels/web/frontend/src/App.tsx"]
 ---
 
 # 外部 Claude 与 Codex CLI 智能体的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/common-core/feature-mcp.md b/knowledge/repos/jiuwenswarm/components/common-core/feature-mcp.md
index bf5a9cb4..ac858057 100644
--- a/knowledge/repos/jiuwenswarm/components/common-core/feature-mcp.md
+++ b/knowledge/repos/jiuwenswarm/components/common-core/feature-mcp.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/MCP配置.md
 feature: "mcp"
 entry_points: ["jiuwenswarm/common/mcp_config.py"]
-source_globs: ["jiuwenswarm/common/mcp_config.py"]
+source_globs: ["jiuwenswarm/common/mcp_config.py", "jiuwenswarm/server/agent_ws_server.py", "jiuwenswarm/server/runtime/mcp/call_timeout_patch.py", "jiuwenswarm/server/runtime/agent_adapter/interface_code.py", "jiuwenswarm/server/runtime/mcp/cli_driver.py", "jiuwenswarm/server/runtime/mcp/state_store.py", "jiuwenswarm/server/runtime/mcp/credential.py", "jiuwenswarm/server/runtime/mcp/registry.py", "jiuwenswarm/common/config.py", "jiuwenswarm/server/runtime/mcp/exc_group.py", "jiuwenswarm/server/runtime/agent_manager.py", "jiuwenswarm/server/runtime/agent_adapter/interface_deep.py", "jiuwenswarm/server/runtime/mcp/package_manifest.py", "jiuwenswarm/server/runtime/marketplace/asset_mcp_publish_converter.py", "jiuwenswarm/server/runtime/mcp/__init__.py", "jiuwenswarm/runtime/mcp_references.py", "jiuwenswarm/server/runtime/agent_adapter/interface.py", "jiuwenswarm/agents/swarm/assembly.py"]
 ---
 
 # MCP 配置、凭据与资源 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/common-core/feature-models.md b/knowledge/repos/jiuwenswarm/components/common-core/feature-models.md
index 0dd5ef3c..705f93c0 100644
--- a/knowledge/repos/jiuwenswarm/components/common-core/feature-models.md
+++ b/knowledge/repos/jiuwenswarm/components/common-core/feature-models.md
@@ -11,7 +11,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/配置信息.md
 feature: "models"
 entry_points: ["jiuwenswarm/common/model_catalog.py", "jiuwenswarm/common/model_config_validation.py"]
-source_globs: ["jiuwenswarm/common/model_catalog.py", "jiuwenswarm/common/model_config_validation.py", "jiuwenswarm/common/model*.py"]
+source_globs: ["jiuwenswarm/common/model_catalog.py", "jiuwenswarm/common/model_config_validation.py", "jiuwenswarm/common/model*.py", "jiuwenswarm/common/config_panel/config_set_handlers.py", "jiuwenswarm/common/config_panel/models_handlers.py", "jiuwenswarm/common/config_panel/tui_models_handlers.py", "jiuwenswarm/common/config.py", "jiuwenswarm/common/auth/apig.py", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ChatModelSelector.tsx", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ChatPanel.css", "jiuwenswarm/server/agent_ws_server.py", "jiuwenswarm/server/runtime/agent_adapter/interface_deep.py", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/models/ContextWindowField.tsx", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/models/contextWindow.ts", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/models/FreeModelsSettings.tsx", "jiuwenswarm/server/control/config_service.py", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/agent/generationModels.ts", "jiuwenswarm/llm_provider_compat_patch.py", "jiuwenswarm/llm_sse_patch.py", "jiuwenswarm/common/auth/model_catalog.py", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/models/FreeModelSettingsDialog.tsx", "jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/validate_config.py", "jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/config_writer.py", "jiuwenswarm/server/runtime/model_compiler_adapter.py", "jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/models/modelAdapters.ts", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/models/modelValidation.ts", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/models/modelListOperations.ts", "jiuwenswarm/channels/web/frontend/src/components/ModelProviderIcon/index.css", "jiuwenswarm/channels/web/frontend/src/components/ModelProviderIcon/index.tsx", "jiuwenswarm/channels/web/frontend/src/assets/providers/index.ts", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/models/modelReasoning.ts", "jiuwenswarm/common/model_selection.py", "jiuwenswarm/common/model_errors.py", "jiuwenswarm/common/model_migration.py", "jiuwenswarm/server/runtime/model_routing_registry.py", "jiuwenswarm/channels/web/frontend/src/features/modelSetupGuide/ModelSetupGuide.css", "jiuwenswarm/channels/web/frontend/src/features/modelSetupGuide/ModelSetupGuide.tsx", "jiuwenswarm/channels/web/frontend/src/features/modelSetupGuide/modelSetupGuideState.ts", "jiuwenswarm/common/model_vendor_registry.py", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/models/definition.ts", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/models/index.ts", "jiuwenswarm/common/openrouter_attribution.py", "jiuwenswarm/common/reasoning_config.py", "jiuwenswarm/common/reasoning_injector.py", "jiuwenswarm/agents/harness/common/rsi/model_resolver.py", "jiuwenswarm/channels/web/frontend/src/features/rsi/components/CreateExperimentDialog.tsx", "jiuwenswarm/runtime/model_catalog.py", "jiuwenswarm/runtime/service.py", "jiuwenswarm/channels/web/frontend/src/features/settings/services/settingsContract.ts", "jiuwenswarm/channels/web/frontend/src/features/settings/services/useSettingsConfig.ts", "jiuwenswarm/channels/tui/frontend/src/app-state.ts", "jiuwenswarm/channels/tui/frontend/src/ui/app-screen.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/model.ts", "jiuwenswarm/channels/web/frontend/src/stores/sessionStore.ts", "jiuwenswarm/channels/web/frontend/src/components/form/components/Form.tsx", "jiuwenswarm/channels/web/frontend/src/components/form/components/FormDialog.tsx", "jiuwenswarm/channels/web/frontend/src/components/form/core/FormStore.ts", "jiuwenswarm/channels/web/frontend/src/components/form/hooks/useForm.ts", "jiuwenswarm/channels/web/frontend/src/components/form/hooks/useFormState.ts", "jiuwenswarm/channels/web/frontend/src/components/form/index.ts", "jiuwenswarm/channels/web/frontend/src/components/form/types.ts", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/channels/forms/FeishuChannelForm.tsx", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/channels/forms/StandardChannelForm.tsx", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/channels/useSettingsChannelsController.ts", "jiuwenswarm/channels/web/frontend/src/features/free-models/campaign.ts", "jiuwenswarm/channels/web/frontend/src/features/free-models/chatError.ts", "jiuwenswarm/channels/web/frontend/src/features/free-models/points.ts", "jiuwenswarm/channels/web/frontend/src/features/free-models/quotaReset.ts", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/agent/GenerationModelConfigDialog.tsx", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/models/ModelDialog.tsx", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/models/ModelNameField.tsx", "jiuwenswarm/channels/web/frontend/src/components/ModelPicker/index.tsx", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/models/ModelProviderSelect.tsx", "jiuwenswarm/channels/web/frontend/src/App.tsx", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/models/ModelsSettings.tsx", "jiuwenswarm/gateway/app_gateway.py"]
 ---
 
 # 模型平台与 API 配置 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/_index.md b/knowledge/repos/jiuwenswarm/components/config-resources/_index.md
index 6ad1f5b9..f6ca219d 100644
--- a/knowledge/repos/jiuwenswarm/components/config-resources/_index.md
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/_index.md
@@ -43,3 +43,46 @@ sources: []
 - [swarmskill-creator-scripts](swarmskill-creator-scripts/_index.md)
 - [xlsx-scripts](xlsx-scripts/_index.md)
 - [内置日报技能：采集、报告接口与模型配置](knowledge-config-resources.md) — 说明接口、配置与集成边界，关联源码和维护者文档。
+- [Agent 模板分层校验器（validate_template.py / validate_hot_load_worker.py）](feature-agent-template-layered-validation.md)
+- [extract_arxiv_visuals v2.2 — arXiv 论文 Figure/Table 检测与高清导出](feature-arxiv-visual-extraction.md)
+- [Chrome Trace JSON 生成器（trace_collector）](feature-ascend-chrome-trace-generator.md)
+- [ascend-moe-optimizer-trace-analyzer CLI 主流程](feature-ascend-trace-analysis-pipeline.md)
+- [instrument_operator.py：TRACE_POINT 自动埋点改写脚本](feature-ascend-trace-auto-instrumentation.md)
+- [插桩编译安全静态检查器（check_compile_safety.py）](feature-ascend-trace-compile-safety-checker.md)
+- [插桩计划生成器（generate_instrumentation_plan.py）](feature-ascend-trace-instrumentation-planner.md)
+- [TRACE_POINT 预处理器与 point_map 映射导出（ascend-moe-optimizer-auto-trace skill）](feature-ascend-trace-preprocessor.md)
+- [自包含审计可视化 HTML 报告生成器（render_audit_report.py）](feature-audit-report-html-renderer.md)
+- [Cross-Channel Session History Search Skill (search_history.py)](feature-cross-channel-history-search-skill.md)
+- [docx-pro Word 文档操作 CLI](feature-docx-pro-cli.md)
+- [财务文档解析 Skill（financial_parser.py）](feature-financial-document-parser.md)
+- [GitHub Issue 反馈创建脚本（open_github_issue.py）](feature-github-issue-feedback-script.md)
+- [华为云 MaaS 委托授权自动化（auto_authorize.py）](feature-huawei-maas-cdp-authorize.md)
+- [check_account — 华为云账号实名认证状态检测脚本](feature-huawei-realname-account-check.md)
+- [华为云 MaaS 预置服务批量开通脚本 auto_open_model.py](feature-maas-auto-open-models.md)
+- [add_slide.py — 解包 PPTX 幻灯片添加工具](feature-opc-add-slide.md)
+- [OOXML 打包与 schema 校验（opc/pack.py）](feature-opc-pack-validate.md)
+- [plugin-creator 插件包脚手架初始化（init_plugin.py）](feature-plugin-package-initializer.md)
+- [plugin-creator 插件包分层校验器（validate_plugin.py L0/L1/L2）](feature-plugin-package-layered-validator.md)
+- [一键成片流水线与质量门禁（finalize_deck.py）](feature-ppt-deck-finalize.md)
+- [PPT 执行锁（execution-lock.json）语义校验器](feature-ppt-execution-lock-validator.md)
+- [PPT 图表面板布局引擎（figure-panel.js）](feature-ppt-figure-panel-layout.md)
+- [Deck Thumbnail Contact-Sheet Renderer (thumbnail.py)](feature-ppt-opc-thumbnail.md)
+- [PPTX 结构与可读性审计脚本（audit_pptx.py 及配套 QA 脚本）](feature-pptx-structural-audit.md)
+- [skill-gen CLI（sop-text / url-fetch 子命令）](feature-skill-generator-cli.md)
+- [skill-omni-creation 网页抓取到统一 Stage01 Blocks（scrape_page）](feature-skill-page-scrape-blocks.md)
+- [SOP 结构化抽取（parse_sop_raw_text / parse_sop_file）](feature-sop-structure-extraction.md)
+- [analyze_video.py：视频粗扫抽帧与审核批次门控](feature-video-coarse-scan-frame-extraction.md)
+- [XLSX Computed Column Adder (xlsx_add_column.py)](feature-xlsx-add-computed-column.md)
+- [XLSX 公式静态校验（formula_check.py）](feature-xlsx-formula-check.md)
+- [XLSX Row Insert with Range Extension（jiuwenswarm skills/xlsx 脚本）](feature-xlsx-insert-row.md)
+- [XLSX 只读结构读取器与编辑损伤差分（xlsx_reader.py）](feature-xlsx-reader-structural-diff.md)
+- [XLSX Skill 格式保留解包/重打包（xlsx_unpack.py / xlsx_pack.py）](feature-xlsx-workbook-unpack-repack.md)
+- [进阶版日报/周报/月报生成器 Skill（advanced-daily-report）](feature-daily-report-skill.md)
+- [华为云 MaaS API Key 自动创建与捕获（auto_create_apikey）](feature-huawei-maas-apikey-creation.md)
+- [local-doc-ocr：本地离线 OCR 管线（RapidOCR：PDF/图片 → Markdown）](feature-local-doc-ocr-offline.md)
+- [prepare_evidence.py — Evidence Plan Preparation and Review Lifecycle](feature-ppt-evidence-preparation.md)
+- [PPT 系统架构图原生形状渲染引擎（system-diagram.js）](feature-ppt-system-diagram-renderer.md)
+- [RSI 数据集任务文件夹完整性预检 check_folder.py](feature-rsi-dataset-folder-check.md)
+- [XLSX 技能环境自检（doctor.py）](feature-xlsx-doctor-selfcheck.md)
+- [符号审计完整性 HMAC 签名与信任验证（audit_integrity.py）](feature-audit-integrity-hmac-signing.md)
+- [openJiuwen-DeepSearch 深度研究执行管线](feature-deepsearch-research-pipeline.md)
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-agent-template-layered-validation.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-agent-template-layered-validation.md
new file mode 100644
index 00000000..f1c4c404
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-agent-template-layered-validation.md
@@ -0,0 +1,48 @@
+---
+title: "Agent 模板分层校验器（validate_template.py / validate_hot_load_worker.py）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_template.py:L10-L14, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_template.py:L949-L987, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_hot_load_worker.py:L1-L11, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_template.py:L1-L8, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_template.py:L860-L907, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_hot_load_worker.py:L1-L5, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_template.py:L915-L946, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_hot_load_worker.py:L150-L155, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_template.py:L148-L173, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_template.py:L953-L959, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_template.py:L972-L974, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_template.py:L35-L36]
+feature: "agent-template-layered-validation"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_template.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_template.py", "jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_hot_load_worker.py"]
+---
+
+# Agent 模板分层校验器（validate_template.py / validate_hot_load_worker.py）
+
+<!-- kb:knowledge owner=feature-agent-template-layered-validation facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**入口与调用契约**
+
+主入口 `validate_template.py <path|agent-name> [--no-hot-load>`：目标既可以是包目录路径，也可以是 `local/` 下的 agent 名。退出码 0 表示三层全部 PASS，1 表示失败；`--no-hot-load` 时 L2 标记 SKIP，结论以 stdout 的 RESULT 行为准（PARTIAL/PASS/FAIL）。热加载 worker `validate_hot_load_worker.py <package-dir>` 由主脚本以子进程调用，在 stdout 最后一行输出一个 JSON 对象（status/errors/notes/skip_reason/skip_fix），自身退出码 0=pass、1=fail、2=skip。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_template.py:L10–L14](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_template.py#L10-L14), [jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_template.py:L949–L987](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_template.py#L949-L987), [jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_hot_load_worker.py:L1–L11](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_hot_load_worker.py#L1-L11)
+
+<!-- kb:knowledge owner=feature-agent-template-layered-validation facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**三层结构与进程边界**
+
+校验分三层：L0 规范与质量（占位符残留、展示字段）、L1 静态校验（加载阻塞项，纯 stdlib 的 json/ast/文件系统）、L2 热加载（真实 harness 加载链）。L0/L1 在主进程一趟跑完并全量报错，只有两者都通过才执行 L2；L2 的全部 openjiuwen 运行时副作用（Runner.resource_mgr、DeepAgent）隔离在子进程 worker 中，主脚本不 import openjiuwen，只解析 worker stdout 最后一个 JSON 行灌回 Layer 结果对象。Layer 是统一的结果容器：errors 阻塞、warnings 提示、notes 记事实，另带 skip_reason/skip_fix 表达“未执行而非通过”。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_template.py:L1–L8](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_template.py#L1-L8), [jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_template.py:L860–L907](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_template.py#L860-L907), [jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_hot_load_worker.py:L1–L5](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_hot_load_worker.py#L1-L5)
+
+<!-- kb:knowledge owner=feature-agent-template-layered-validation facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证方式**
+
+Inference / 设计推断（非作者历史意图）：
+
+所示片段中没有针对这两个脚本的自动化测试；验证入口即脚本自身的 CLI：`validate_template.py <path|agent-name>`，输出各层渲染的报告和 `RESULT:`/`NEXT:` 汇总行。L2 worker 的可用性依赖运行环境装有 openjiuwen——缺失时返回 skip 并提示“改用 JiuwenSwarm 的 venv python 重跑”，这本身构成对环境前置条件的运行时检查。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_template.py:L915–L946](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_template.py#L915-L946), [jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_hot_load_worker.py:L150–L155](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_hot_load_worker.py#L150-L155)
+
+<!-- kb:knowledge owner=feature-agent-template-layered-validation facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**配置项与 CLI 参数**
+
+可配置项集中在三处。环境变量 `JIUWENSWARM_DATA_DIR` 决定数据根目录，缺省回退到 `~/.jiuwenswarm`，模板包默认在 `<data>/agent/workspace/plugins/agent_templates/local/` 下按名解析（validate_template.py:L148-L173）。CLI 参数有两个：位置参数 `target`（包目录路径或 local/ 下的 agent-name），以及 `--no-hot-load` 只跑 L0+L1 并把 L2 标记为显式 SKIP（L953-L959、L972-L974）。L2 子进程的运行参数硬编码：worker 路径取同目录的 validate_hot_load_worker.py，超时 120 秒（L35-L36）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_template.py:L148–L173](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_template.py#L148-L173), [jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_template.py:L953–L959](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_template.py#L953-L959), [jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_template.py:L972–L974](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_template.py#L972-L974), [jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_template.py:L35–L36](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/validate_template.py#L35-L36)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-arxiv-visual-extraction.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-arxiv-visual-extraction.md
new file mode 100644
index 00000000..5a1dbda1
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-arxiv-visual-extraction.md
@@ -0,0 +1,54 @@
+---
+title: "extract_arxiv_visuals v2.2 — arXiv 论文 Figure/Table 检测与高清导出"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py:L1203-L1217, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py:L962-L997, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py:L423-L432, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py:L1363-L1406, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py:L50-L56, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py:L125-L130, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py:L1410-L1471, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py:L1191-L1196, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py:L1363-L1369, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py:L22-L24, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py:L96-L127, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py:L891-L897, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py:L1334-L1337, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py:L1413-L1437, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py:L1126-L1148, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py:L1168-L1177]
+feature: "arxiv-visual-extraction"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py"]
+---
+
+# extract_arxiv_visuals v2.2 — arXiv 论文 Figure/Table 检测与高清导出
+
+<!-- kb:knowledge owner=feature-arxiv-visual-extraction facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**候选流水线与数据流**
+
+extract_visuals 采用四源候选→合并→去重→清洗→渲染的流水线：先加载可选 PDFFigures2 JSON（confidence 0.96），再跑 PyMuPDF find_tables（0.82/0.66），caption 启发式为 figure（0.62）和 table（0.55）补充候选；merge_same_label_tables 合并同页同标签的表格碎片，deduplicate 按 source 优先级（pdffigures2_json 最高）加 IoU>0.42 / 包含率>0.78 / 同标签轻微重叠规则去重；最后 sanitize_margin_artifacts 对所有路径（含外部 PDFFigures2 框）统一剔除页边 arXiv 戳记，逐候选渲染 PNG 并写 manifest。文档还注明清理刻意放在去重之后，保证每条路径得到同样的裁剪治理。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py:L1203–L1217](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py#L1203-L1217), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py:L962–L997](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py#L962-L997), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py:L423–L432](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py#L423-L432)
+
+<!-- kb:knowledge owner=feature-arxiv-visual-extraction facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**命令行设置**
+
+CLI 提供 --dpi（默认 300，即 DEFAULT_DPI）、--padding（默认 4.0 PDF point）、--debug-dpi（默认 120）、--output（默认 ./paper-assets-<paper-id>）、--keep-pages、--force、--include-uncaptioned-tables（默认关闭，因流程图/仪表盘易被误判为表格）、--pdffigures-json 与 --no-auto-install。main() 校验 dpi/debug_dpi 必须为正、padding 非负，否则 parser.error。--no-auto-install 在模块导入期、第三方 import 之前就从 sys.argv 解析，用于禁止自动 pip 安装 PyMuPDF（>=1.24,<2）与 Pillow（>=10,<13）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py:L1363–L1406](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py#L1363-L1406), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py:L50–L56](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py#L50-L56), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py:L125–L130](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py#L125-L130)
+
+<!-- kb:knowledge owner=feature-arxiv-visual-extraction facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**CLI 入口与错误契约**
+
+公开入口是命令行 main()：接受 arXiv ID/URL、HTTP(S) PDF URL 或本地 PDF 路径，核心逻辑在 extract_visuals(pdf_path, output, resource, options)，返回 manifest dict 并写入 manifest.json。参数校验（dpi/debug_dpi 为正、padding 非负）发生在 L1411–L1418，位于 try 块之前，parser.error 直接退出；只有 L1420 之后抛出的异常才被 L1466–L1471 捕获——KeyboardInterrupt 返回 130，其余异常打印错误并返回 1。依赖安装则在模块导入期（L125–L130 之前的 ensure_dependencies）完成，不在此 try 覆盖范围内。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py:L1410–L1471](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py#L1410-L1471), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py:L1191–L1196](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py#L1191-L1196), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py:L1363–L1369](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py#L1363-L1369)
+
+<!-- kb:knowledge owner=feature-arxiv-visual-extraction facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**零外部工具链与人工复核要求**
+
+docstring 明确脚本"intentionally Python-only"——不依赖 Bash/curl/Java/Git/WSL，缺失的 PyMuPDF/Pillow 默认在模块导入期自动 pip 安装（--no-auto-install 关闭）；PDFFigures2 结果以可选 JSON 文件接入，使脚本本身不需要 Java 运行时。代价是检测为启发式：manifest 固定写入 quality_note，提示 PyMuPDF 表格检测与 caption 启发式属于自动检测，应查看 debug/ 与 contact_sheet.png 做人工视觉复核。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py:L22–L24](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py#L22-L24), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py:L96–L127](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py#L96-L127), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py:L891–L897](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py#L891-L897), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py:L1334–L1337](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py#L1334-L1337)
+
+<!-- kb:knowledge owner=feature-arxiv-visual-extraction facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**参数校验与可视化复核产物**
+
+main() 在解析后用 parser.error 校验 --dpi/--debug-dpi 必须为正、--padding 非负，并在提取前读取文件前 5 字节验证 %PDF- 魔数。运行后生成复核用的可视化产物：make_debug_pages 为每个含候选的页面渲染红框标注图，标签含 kind、label 与 source；make_contact_sheet 把成功提取的缩略图排成网格，缩略图不少于 3 张时为 3 列，不足时列数等于缩略图数，无缩略图则不生成该文件。manifest 的 summary 记录 figure/table/visual/failure 计数。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py:L1413–L1437](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py#L1413-L1437), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py:L1126–L1148](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py#L1126-L1148), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py:L1168–L1177](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/extract_arxiv_visuals_v2_2.py#L1168-L1177)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-ascend-chrome-trace-generator.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-ascend-chrome-trace-generator.md
new file mode 100644
index 00000000..c809f484
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-ascend-chrome-trace-generator.md
@@ -0,0 +1,46 @@
+---
+title: "Chrome Trace JSON 生成器（trace_collector）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_collector.py:L32-L55, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_collector.py:L22-L29, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_collector.py:L338-L352, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_utils.py:L124-L148, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_collector.py:L372-L382, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_utils.py:L71-L85, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_collector.py:L367-L400, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_collector.py:L58-L90, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/verify_trace_scaffold.py:L14-L54, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_collector.py:L104-L125, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_collector.py:L338-L363]
+feature: "ascend-chrome-trace-generator"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_collector.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_collector.py", "jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_save.py", "jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_utils.py", "jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/inspect_rank_pt.py", "jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/bootstrap_trace_toolchain.py", "jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/verify_trace_scaffold.py"]
+---
+
+# Chrome Trace JSON 生成器（trace_collector）
+
+<!-- kb:knowledge owner=feature-ascend-chrome-trace-generator facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**数据流与处理阶段**
+
+流水线分四段：(1) load_all_ranks 用 glob 按文件名解析 rank id，torch.load 每个由 trace_utils.save_profiling_data 产出的按核类型分组的 tensor 列表；(2) parse_profiling_data 按核读取记录——tensor[core,0] 是计数器（记录数 = 计数 - 1），ID 自 [1+i] 正向、时间戳自 [-2-i] 反向读取，与首时间戳 [-1] 做无符号差后除以 CLOCK_DIVISOR 得微秒；组合 ID 拆为低 32 位 base_point_id 与高 32 位 extra_id（均按补码转有符号）。(3) generate_chrome_trace 按 (rank, core_type, core_id) 生成 pid/tid 元数据，做 B/E 配对与深度过滤；(4) 写出 {traceEvents, displayTimeUnit:'us', otherData:{统计与参数}}。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_collector.py:L32–L55](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_collector.py#L32-L55), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_collector.py:L22–L29](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_collector.py#L22-L29), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_collector.py:L338–L352](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_collector.py#L338-L352), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_utils.py:L124–L148](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_utils.py#L124-L148)
+
+<!-- kb:knowledge owner=feature-ascend-chrome-trace-generator facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**配置项与默认值**
+
+命令行配置：`-o/--output`（默认 chrome_trace.json）、`--clock-divisor`（float，默认 50.0，即 MHz，cycle→us；赋给模块级 CLOCK_DIVISOR）、`--extra-mode`（legacy|seq，默认 seq）、`--depth`（int，默认 0 = 不过滤；非 0 时按 depth_from_leaf <= depth 保留区间）。上游 trace_utils 还受环境变量 MOE_USE_1C2V（默认 "0"；为 "1" 时核数列表从 [24,48] 变为 [24,24,24] 并改用 1c2v 核映射）以及 base.h 宏 PROF_SIZE_PER_CORE（默认 2048）和 ENABLE_MOE_PROFILING 影响。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_collector.py:L372–L382](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_collector.py#L372-L382), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_utils.py:L71–L85](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_utils.py#L71-L85)
+
+<!-- kb:knowledge owner=feature-ascend-chrome-trace-generator facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**入口与调用契约**
+
+公开入口是命令行 `main()`：位置参数 `data_dir`（含 rank*.pt 的目录）与 `mapping_file`（point_map.json），选项 `-o/--output`（默认 chrome_trace.json）、`--clock-divisor`、`--extra-mode`、`--depth`。主流程为 load_all_ranks → （空则报错并提前 return）→ load_mapping → diagnose_mapping_overlap → generate_chrome_trace。generate_chrome_trace 也可作为库函数直接调用，返回写出的 trace 字典。错误契约：load_all_ranks 对单个 .pt 加载失败仅告警跳过；load_mapping 对文件缺失或非对象结构返回 {}，但 open/json.load 未捕获异常，损坏 JSON 会直接抛出。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_collector.py:L367–L400](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_collector.py#L367-L400), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_collector.py:L58–L90](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_collector.py#L58-L90)
+
+<!-- kb:knowledge owner=feature-ascend-chrome-trace-generator facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**现有验证入口**
+
+verify_trace_scaffold.py 检查构建目录是否包含 trace_preprocessor/trace_utils/trace_save/trace_collector 四个必需脚本，缺文件时退出码 1；可选 --compile-script 检查编译脚本是否含 TRACE_PREPROCESSOR_HOOK_START/END 钩子标记。运行期诊断：generate_chrome_trace 结束时若 skipped_no_mapping>0 发出警告，统计写入 otherData；diagnose_mapping_overlap 仅当 rank*.pt 中的唯一 id 集合与 point_map 键集合均非空且交集为空时，才提示 point_map.json 与内核构建不匹配、应改用同一 ascend_kernels_*_proj 目录编译进 OPP 的 point_map.json，并输出双方样本 id。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/verify_trace_scaffold.py:L14–L54](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/verify_trace_scaffold.py#L14-L54), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_collector.py:L104–L125](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_collector.py#L104-L125), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_collector.py:L338–L363](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_collector.py#L338-L363)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-ascend-trace-analysis-pipeline.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-ascend-trace-analysis-pipeline.md
new file mode 100644
index 00000000..ec2b80a2
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-ascend-trace-analysis-pipeline.md
@@ -0,0 +1,54 @@
+---
+title: "ascend-moe-optimizer-trace-analyzer CLI 主流程"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/metrics.py:L12-L25, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/metrics.py:L460-L505, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/metrics.py:L526-L560, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/diagnosis.py:L184-L209, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/app.py:L50-L99, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/app.py:L303-L324, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/llm_analysis.py:L171-L221, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/app.py:L94-L99, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/app.py:L172-L182, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/metrics.py:L365-L365, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/app.py:L50-L91, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/llm_analysis.py:L171-L185, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/llm_analysis.py:L224-L250, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/phase_mapper.py:L70-L87, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/app.py:L164-L197, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/parser.py:L144-L169, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/metrics.py:L122-L162]
+feature: "ascend-trace-analysis-pipeline"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/app.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/app.py", "jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/phase_mapper.py", "jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/diagnosis.py", "jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/llm_analysis.py", "jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/metrics.py", "jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/parser.py", "jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/plots.py", "jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/reporter.py"]
+---
+
+# ascend-moe-optimizer-trace-analyzer CLI 主流程
+
+<!-- kb:knowledge owner=feature-ascend-trace-analysis-pipeline facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**核组归因、重叠与空洞分析**
+
+除 phase/category/name/tid 等常规汇总外，组件针对 Ascend 1C2V 场景做了核组归因：从 tid 形如 `typeN_coreN` 中提取 core_type，映射到 `cube`、`vector_recv`、`vector_send` 三个核组，并输出按核组切分的 phase/category 汇总。`build_overlap_summary` 计算所有 phase 两两的区间重叠（含 overlap_ratio_min 等多口径），`build_bubble_summary` 针对 processing/dispatch_gmm1/gmm2_combine 三个父 phase 计算子阶段未覆盖的空洞（bubble）。自动诊断据此产出阈值化 findings（如 wait 占比、dispatch_gmm1 与 gmm2_combine 的流水覆盖强弱）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/metrics.py:L12–L25](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/metrics.py#L12-L25), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/metrics.py:L460–L505](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/metrics.py#L460-L505), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/metrics.py:L526–L560](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/metrics.py#L526-L560), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/diagnosis.py:L184–L209](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/diagnosis.py#L184-L209)
+
+<!-- kb:knowledge owner=feature-ascend-trace-analysis-pipeline facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**CLI 入口、参数与错误契约**
+
+公共入口是 `app.py` 的 `main()`（`__main__` 下以 INFO 级别初始化 logging 后调用）。CLI 由 argparse 定义：必填 `--trace`，可选 `--phase-map`（默认 `config/phase_map.yaml`）、`--output-dir`（默认 `output`）、`--top-n`（默认 20）、`--llm-analysis`、`--llm-command`、`--llm-timeout`（默认 120 秒）。运行前 `validate_inputs` 对 trace 与 phase map 做存在性检查，缺失时抛 `FileNotFoundError`。LLM 分析是可选支路：`--llm-analysis` 开启后命令经 `shlex` 解析并作为子进程执行，`run_llm_command` 显式捕获 shlex `ValueError`、`FileNotFoundError` 与 `subprocess.TimeoutExpired`，分别返回 error/timeout 状态字典；主流程仅在 `--llm-analysis` 开启且 status 非 ok 时记录 warning，未开启则返回 disabled 状态。子进程其他异常类型不在所示捕获范围内。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/app.py:L50–L99](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/app.py#L50-L99), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/app.py:L303–L324](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/app.py#L303-L324), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/llm_analysis.py:L171–L221](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/llm_analysis.py#L171-L221)
+
+<!-- kb:knowledge owner=feature-ascend-trace-analysis-pipeline facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**入口存在性检查与运行结束日志**
+
+运行前的显式校验只有 `validate_inputs` 的两个文件存在性检查（trace 与 phase map），缺失即抛 `FileNotFoundError`，所示代码中没有对输出产物的一致性回读。运行结束后 `log_run_summary` 在 INFO 级别记录 overview 计数（实例数、phase/name/pid/tid 数、核组、wall time）、diagnosis headline，以及 phase/category 摘要的前 10 行和全部 core group 行（core_group_summary 本身按 cube/vector_recv/vector_send 的固定组序排列，不是按 union_us 全局排序），仅作日志呈现，不构成第二次校验。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/app.py:L94–L99](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/app.py#L94-L99), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/app.py:L172–L182](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/app.py#L172-L182), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/metrics.py:L365–L365](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/metrics.py#L365-L365)
+
+<!-- kb:knowledge owner=feature-ascend-trace-analysis-pipeline facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**CLI 参数与 phase map 加载**
+
+CLI 仅 --trace 必填；可选 --phase-map（默认 config/phase_map.yaml）、--output-dir（默认 output）、--top-n（默认 20，控制报告与图表行数）、--llm-analysis（开关）、--llm-command（默认 None）、--llm-timeout（默认 120 秒）。命令解析优先取显式 --llm-command，否则回退环境变量 TRACE_ANALYSIS_LLM_CMD；命令经 shlex.split 拆分，若拆分结果为空 argv（例如仅空白字符串，此时 `command or env` 为真值、不再回退环境变量）则返回 not_configured 状态。phase map 加载优先用 PyYAML 的 safe_load，PyYAML 缺失时退回一个只支持固定缩进结构的自研 YAML 子集解析器。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/app.py:L50–L91](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/app.py#L50-L91), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/llm_analysis.py:L171–L185](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/llm_analysis.py#L171-L185), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/llm_analysis.py:L224–L250](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/llm_analysis.py#L224-L250), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/phase_mapper.py:L70–L87](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/phase_mapper.py#L70-L87)
+
+<!-- kb:knowledge owner=feature-ascend-trace-analysis-pipeline facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**主流程：解析、映射、九张汇总表与诊断支路**
+
+main() 按固定顺序组织数据流：parse_trace_json 统一解析 Chrome JSON 的 ph=='X' 完整事件与 B/E 栈配对事件（按 pid/tid/name 配对，孤立或时间反常的丢弃）；PhaseMapper 用 YAML phase 规则把事件名映射为 phase；build_phase_instances 只保留成功映射的区间行并派生 category/core_group 等字段。随后构建九张汇总表（phase/category/core_group/phase_core_group/category_core_group/name/phase_tid/overlap/bubble）与 overview；自动诊断接收 overview 加其中八张表（不含 phase_tid_summary）。图表与 LLM 分析是可选支路，最终统一落到 output 目录的 CSV、report.md 与 summary/diagnosis JSON。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/app.py:L164–L197](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/app.py#L164-L197), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/parser.py:L144–L169](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/parser.py#L144-L169), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/metrics.py:L122–L162](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-trace-analyzer/analyzers/metrics.py#L122-L162)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-ascend-trace-auto-instrumentation.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-ascend-trace-auto-instrumentation.md
new file mode 100644
index 00000000..ca0fa616
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-ascend-trace-auto-instrumentation.md
@@ -0,0 +1,64 @@
+---
+title: "instrument_operator.py：TRACE_POINT 自动埋点改写脚本"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L108-L124, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L71-L75, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L111-L115, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L61-L68, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L2-L8, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L101-L105, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L77-L89, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L88-L98, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L119-L124, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L21-L24, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L36-L58, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L71-L98, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L101-L124, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L48-L58, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L67-L68, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L95-L98]
+feature: "ascend-trace-auto-instrumentation"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py"]
+---
+
+# instrument_operator.py：TRACE_POINT 自动埋点改写脚本
+
+<!-- kb:knowledge owner=feature-ascend-trace-auto-instrumentation facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**公开入口与命令行契约**
+
+脚本作为命令行工具运行：`main()` 解析 `--target`（必需，源文件或目录）、`--root-label`（默认 `processing`）、`--dry-run`（预览开关）。对每个目标文件调用 `apply_file(path, root_label, dry_run)`，返回 `(插桩函数数, 日志消息)`；目录模式下通过 `iter_targets` 递归收集 C/C++ 源文件后逐个处理。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L108–L124](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py#L108-L124), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L71–L75](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py#L71-L75)
+
+<!-- kb:knowledge owner=feature-ascend-trace-auto-instrumentation facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**可配置项与默认值**
+
+仅三个 CLI 参数：`--target`（必需）、`--root-label` 默认 `processing`、`--dry-run` 标志（默认关闭即直接写盘）。root_label 只作用于名为 `process`（不区分大小写）的函数；其余函数标签由 `normalize_label` 从函数名派生（驼峰转连字符、下划线转连字符、转小写）。文件头注释还提到 "Max depth defaults to 5"，但所示代码中没有对应参数或逻辑。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L111–L115](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py#L111-L115), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L61–L68](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py#L61-L68), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L2–L8](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py#L2-L8)
+
+<!-- kb:knowledge owner=feature-ascend-trace-auto-instrumentation facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的行为**
+
+对 `.h/.hpp/.c/.cc/.cpp` 后缀的文件（或单个指定文件）做函数级 TRACE_POINT 插桩：函数体开头插入 `"B"`、结尾插入 `"E"` 标记，缩进跟随原函数。幂等性通过 `should_skip` 实现——函数体已含 `MoeTracing(` 或 `TRACE_POINT(` 则跳过；无函数或全部已插桩的文件返回 0 且不写盘。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L101–L105](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py#L101-L105), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L77–L89](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py#L77-L89)
+
+<!-- kb:knowledge owner=feature-ascend-trace-auto-instrumentation facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证方式**
+
+所示片段不含测试；脚本自身提供的验证手段是 `--dry-run`（输出 `plan <path>` 与插桩计数，不写盘）以及每文件的 skip/write 日志和最终的 `instrumented functions: N` 汇总，可用于人工核对改写范围。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L88–L98](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py#L88-L98), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L119–L124](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py#L119-L124)
+
+<!-- kb:knowledge owner=feature-ascend-trace-auto-instrumentation facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**架构与数据流**
+
+脚本是一个独立的纯 Python 命令行改写器，流程为：`main()` 解析 CLI 参数并 `resolve` 目标路径，`iter_targets` 在目录模式下递归收集 `.h/.hpp/.c/.cc/.cpp` 文件；每个文件由 `apply_file` 处理——读入文本、`find_functions` 用单个多行正则 `FUNC_RE` 定位函数签名、`find_match_brace` 做深度计数式花括号配对得到函数体范围，随后在函数体开/闭花括号处插入 `MoeTracing(TRACE_POINT(label, "B"/"E"))`。所有编辑位置先收集再按位置降序一次性写回，最后（非 dry-run 时）整文件重写回磁盘并累计插桩函数数。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L21–L24](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py#L21-L24), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L36–L58](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py#L36-L58), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L71–L98](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py#L71-L98), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L101–L124](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py#L101-L124)
+
+<!-- kb:knowledge owner=feature-ascend-trace-auto-instrumentation facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**设计取舍**
+
+Inference / 设计推断（非作者历史意图）：
+
+选择正则 + 花括号深度计数而非真正的 C++ 解析器：零依赖、实现极短，但代价是识别精度有限——`FUNC_RE` 依赖启发式签名模式，`find_match_brace` 对未闭合文件返回 `len(text)-1`，遇到字符串/注释中的花括号或非常规签名时可能配对错误。幂等性用简单的子串检查实现（函数体含 `MoeTracing(` 或 `TRACE_POINT(` 即跳过），代价是检查的是整个函数体文本而非精确语句。`--dry-run` 提供无副作用预览；实际写盘仅在非 dry-run 分支发生。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L21–L24](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py#L21-L24), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L48–L58](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py#L48-L58), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L67–L68](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py#L67-L68), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py:L95–L98](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/instrument_operator.py#L95-L98)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-ascend-trace-compile-safety-checker.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-ascend-trace-compile-safety-checker.md
new file mode 100644
index 00000000..ea67bba2
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-ascend-trace-compile-safety-checker.md
@@ -0,0 +1,54 @@
+---
+title: "插桩编译安全静态检查器（check_compile_safety.py）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/check_compile_safety.py:L258-L301, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/run_instrumentation_checks.sh:L5-L11, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/check_compile_safety.py:L2-L17, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/check_compile_safety.py:L268-L285, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/validate_trace_points.py:L29-L50, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/check_compile_safety.py:L261-L266, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/check_compile_safety.py:L141-L141, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/check_compile_safety.py:L184-L194, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/check_compile_safety.py:L292-L301, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/validate_trace_points.py:L73-L82, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/run_instrumentation_checks.sh:L1-L11, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/check_compile_safety.py:L9-L17, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/check_compile_safety.py:L274-L285, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/check_compile_safety.py:L138-L168, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/validate_trace_points.py:L34-L50]
+feature: "ascend-trace-compile-safety-checker"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/check_compile_safety.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/check_compile_safety.py", "jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/run_instrumentation_checks.sh", "jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/validate_trace_points.py"]
+---
+
+# 插桩编译安全静态检查器（check_compile_safety.py）
+
+<!-- kb:knowledge owner=feature-ascend-trace-compile-safety-checker facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**命令行入口与退出契约**
+
+入口是 `main()`，通过 argparse 接收位置参数 `operator_dir`（算子根目录，含 op_kernel/ 与 op_host/）和可选开关 `--strict`（把警告当作错误）。检查结果汇总到 `CheckResult`（errors/warnings 两条列表，`ok` 属性表示无错误）；结尾按 PASSED/FAILED 打日志，失败或 strict 下有警告时以退出码 1 结束。配套脚本 `run_instrumentation_checks.sh <file-or-dir>` 用 exec 委托给 `validate_trace_points.py`，参数不足时报 usage 并 exit 1。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/check_compile_safety.py:L258–L301](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/check_compile_safety.py#L258-L301), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/run_instrumentation_checks.sh:L5–L11](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/run_instrumentation_checks.sh#L5-L11)
+
+<!-- kb:knowledge owner=feature-ascend-trace-compile-safety-checker facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**职责与数据流**
+
+这是一个无需真实编译器的静态检查器，模块头部明确说明其目的是在无法本地编译算子的环境中拦截会导致编译失败的常见插桩错误。数据流为：main() 递归收集算子目录下的 .cpp/.h/.hpp（过滤 build_out 与 pregen 路径），逐文件跑五个单文件检查（花括号平衡、预处理指令配对、TRACE_POINT 语法、作用域变量、ENABLE_MOE_PROFILING 守卫），再对 op_kernel 文件做头文件可达性分析，最后做 kernel 与 op_host 输出数一致性检查；各检查把结果写入共享的 CheckResult。读文件统一走 `read_lines`（utf-8，errors=replace）。配套的 validate_trace_points.py 是独立的质量检查器，专注标签命名风格与 B/E 配对计数，二者不共享代码。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/check_compile_safety.py:L2–L17](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/check_compile_safety.py#L2-L17), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/check_compile_safety.py:L268–L285](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/check_compile_safety.py#L268-L285), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/validate_trace_points.py:L29–L50](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/validate_trace_points.py#L29-L50)
+
+<!-- kb:knowledge owner=feature-ascend-trace-compile-safety-checker facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**可配置项**
+
+唯一的运行时配置是 CLI 参数：位置参数 `operator_dir`（要检查的算子根目录）和 `--strict` 布尔开关（warning 升级为 error 并影响退出码）。此外有硬编码在代码里的常量：头文件可达性检查认可的基名集合 {fused_deep_moe_base.h, moe_base.h, moe_dispatch_normal_base.h}，作用域检查回看的 80 行窗口，以及 kernel 系统参数固定按 2 计算；这些不可通过参数调整。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/check_compile_safety.py:L261–L266](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/check_compile_safety.py#L261-L266), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/check_compile_safety.py:L141–L141](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/check_compile_safety.py#L141-L141), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/check_compile_safety.py:L184–L194](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/check_compile_safety.py#L184-L194)
+
+<!-- kb:knowledge owner=feature-ascend-trace-compile-safety-checker facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**测试与验证入口**
+
+所示文件中没有针对这两个 Python 脚本的单元测试；它们本身即是验证工具：check_compile_safety.py 在结束时输出 "PASSED (N files, M warnings, 0 errors)" 或 "FAILED (N issues)" 并以退出码表达结果，validate_trace_points.py 输出检查文件数、label 数及 "validation passed"/"validation failed"。`run_instrumentation_checks.sh` 是对外暴露的批量入口，直接 exec validate_trace_points.py。无法从这些局部输入判断仓库其他位置是否另有测试。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/check_compile_safety.py:L292–L301](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/check_compile_safety.py#L292-L301), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/validate_trace_points.py:L73–L82](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/validate_trace_points.py#L73-L82), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/run_instrumentation_checks.sh:L1–L11](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/run_instrumentation_checks.sh#L1-L11)
+
+<!-- kb:knowledge owner=feature-ascend-trace-compile-safety-checker facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的检查行为**
+
+该脚本在不需要真实编译器的前提下，对算子目录下（过滤 build_out 与 pregen 路径）的 .cpp/.h/.hpp 逐文件执行五项单文件检查：花括号平衡、#if/#ifdef/#ifndef 与 #endif 配对、TRACE_POINT 参数语法（event 必须为 "B" 或 "E" 且 label 非空）、MoeTracing 额外实参的作用域回看，以及 #if ENABLE_MOE_PROFILING 守卫块的嵌套/闭合检查。头文件可达性检查仅针对 op_kernel 目录下的文件：使用 MoeTracing 的文件必须传递包含到基名集合 {fused_deep_moe_base.h, moe_base.h, moe_dispatch_normal_base.h} 之一。另有 kernel 与 op_host 的参数计数一致性检查（warn 级）。配套的 validate_trace_points.py 检查 TRACE_POINT 标签命名风格（小写字母/数字/连字符/空格）与同一标签的 B/E 计数配对，两者不共享代码。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/check_compile_safety.py:L9–L17](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/check_compile_safety.py#L9-L17), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/check_compile_safety.py:L274–L285](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/check_compile_safety.py#L274-L285), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/check_compile_safety.py:L138–L168](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/check_compile_safety.py#L138-L168), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/validate_trace_points.py:L34–L50](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/validate_trace_points.py#L34-L50)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-ascend-trace-instrumentation-planner.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-ascend-trace-instrumentation-planner.md
new file mode 100644
index 00000000..688621ae
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-ascend-trace-instrumentation-planner.md
@@ -0,0 +1,62 @@
+---
+title: "插桩计划生成器（generate_instrumentation_plan.py）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py:L133-L160, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py:L1-L5, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py:L20-L27, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py:L136-L140, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py:L91-L118, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py:L126-L130, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py:L106-L130, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py:L136-L149, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py:L44-L56, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py:L59-L72, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py:L91-L123, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py:L148-L159]
+feature: "ascend-trace-instrumentation-planner"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py"]
+---
+
+# 插桩计划生成器（generate_instrumentation_plan.py）
+
+<!-- kb:knowledge owner=feature-ascend-trace-instrumentation-planner facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**命令行入口与输出契约**
+
+脚本通过 `main()` 提供 CLI：必填 `--root`（算子源码根目录）与 `--entry`（入口函数名），可选 `-o/--output`（默认 `instrumentation_plan.json`）。运行后写出 JSON，包含 `root`、`entry`、`max_depth`（固定 5）和嵌套的 `plan` 树。入口函数不存在时以 `SystemExit("entry function not found: ...")` 退出。脚本自身不修改任何源文件。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py:L133–L160](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py#L133-L160), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py:L1–L5](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py#L1-L5)
+
+<!-- kb:knowledge owner=feature-ascend-trace-instrumentation-planner facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**设置与常量**
+
+唯一可配置输入是三个 CLI 参数（`--root`、`--entry`、`-o/--output`，默认输出文件名为 `instrumentation_plan.json`）。其余为模块级常量：`MAX_DEPTH = 5` 硬编码最大展开深度；`KEYWORDS` 过滤控制流关键字误判为调用；`HOT_WORDS`（wait/sync/send/recv/copy/quant/dequant）命名热词，含这些词的函数不会被当作低价值 helper 合并。无环境变量或配置文件。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py:L20–L27](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py#L20-L27), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py:L136–L140](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py#L136-L140)
+
+<!-- kb:knowledge owner=feature-ascend-trace-instrumentation-planner facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的行为**
+
+从指定入口函数生成插桩计划树：根节点标签固定为 `"processing"`（L92），只有子节点标签经 `normalize_label` 由函数名转换（camelCase→kebab、下划线→连字符，L85-L88、L105）。展开时 `depth_limit` 判定先于 `helper_merge`：超出 `MAX_DEPTH=5` 的子节点标 `merged=True, merge_reason="depth_limit"`（L108-L112），未超深度且命中 `is_low_value_helper` 的才标 `helper_merge`（L114-L118）。含 HOT_WORDS 子串的函数名不视为低价值 helper（L126-L130）。脚本自身不修改源文件（L3-L4）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py:L91–L118](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py#L91-L118), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py:L126–L130](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py#L126-L130)
+
+<!-- kb:knowledge owner=feature-ascend-trace-instrumentation-planner facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**设计取舍**
+
+函数识别与调用提取全部基于正则（`FUNC_DEF_RE`/`CALL_RE`，L20-L24），无需编译数据库或真解析器，代价是只能覆盖匹配该正则形状的定义，调用边也仅按名字匹配已知名集合（L75-L82）。`MAX_DEPTH=5` 限制展开规模以避免大树，但截断只按深度、不看函数重要性。`HOT_WORDS` 的豁免仅针对 helper 合并这一层：含 wait/sync/quant 等子串的名字不会被 `is_low_value_helper` 折叠（L126-L130），但在深度上限处仍会被 `depth_limit` 合并（L108-L112）；判定用的是名字子串而非函数语义。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py:L20–L27](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py#L20-L27), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py:L106–L130](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py#L106-L130)
+
+<!-- kb:knowledge owner=feature-ascend-trace-instrumentation-planner facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证入口**
+
+所示代码中的运行时校验有：argparse 将 `--root` 与 `--entry` 声明为必填参数（L137-L138），以及构建调用图后检查入口函数是否出现在抽取到的函数名集合中，缺失时以 `SystemExit("entry function not found: ...")` 退出（L148-L149）。本片段为单文件脚本，未附带针对 `build_plan`/`extract_functions` 的测试代码或文档验证说明。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py:L136–L149](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py#L136-L149)
+
+<!-- kb:knowledge owner=feature-ascend-trace-instrumentation-planner facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**职责与数据流：从源码扫描到计划树**
+
+单文件 CLI 脚本，职责是只读分析算子源码并产出 JSON 插桩计划，不修改源文件。数据流为三段流水线：`main()` 先用 `iter_code_files` 递归收集 `.h/.hpp/.c/.cc/.cpp` 文件，对每个文件用 `FUNC_DEF_RE` 定位函数定义、`extract_block` 按花括号深度配对提取函数体，并用 `CALL_RE` 收集调用名（剔除控制流关键字），得到 `FuncInfo` 列表（L39-L56、L59-L72）；随后 `build_call_graph` 只保留目标名在已知函数名集合中的边，自调用也被去掉（L75-L82）；最后 `main` 校验入口函数存在后调用 `build_plan` 从入口做 BFS 展开调用图，构建嵌套计划树并由 `main` 写出 JSON（L91-L123、L148-L159）。展开的终止不只是 `MAX_DEPTH=5`：已见的 `(fn, child, depth)` 边会被跳过，超过深度上限的子节点被标记 `merged=True, merge_reason="depth_limit"` 后不再入队，命中 `is_low_value_helper` 的子节点标 `helper_merge` 后同样不再展开（L96-L121）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py:L44–L56](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py#L44-L56), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py:L59–L72](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py#L59-L72), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py:L91–L123](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py#L91-L123), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py:L148–L159](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/generate_instrumentation_plan.py#L148-L159)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-ascend-trace-preprocessor.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-ascend-trace-preprocessor.md
new file mode 100644
index 00000000..cc0f6a36
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-ascend-trace-preprocessor.md
@@ -0,0 +1,64 @@
+---
+title: "TRACE_POINT 预处理器与 point_map 映射导出（ascend-moe-optimizer-auto-trace skill）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py:L120-L124, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/apply_trace_scaffold.sh:L20-L26, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/apply_trace_scaffold.sh:L28-L33, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/patch_build_pipeline.py:L32-L34, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py:L115-L135, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py:L53-L57, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py:L95-L106, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py:L20-L26, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py:L48-L66, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py:L87-L106, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/apply_trace_scaffold.sh:L17-L31, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py:L68-L75, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/apply_trace_scaffold.sh:L23-L31, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py:L32-L43, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py:L77-L83, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py:L89-L92]
+feature: "ascend-trace-preprocessor"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py", "jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/apply_trace_scaffold.sh", "jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/patch_build_pipeline.py"]
+---
+
+# TRACE_POINT 预处理器与 point_map 映射导出（ascend-moe-optimizer-auto-trace skill）
+
+<!-- kb:knowledge owner=feature-ascend-trace-preprocessor facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**可配置项**
+
+工具本身几乎没有配置项：唯一的开关是 `--modify`（替换源码中的 TRACE_POINT 调用），默认只扫描不改写；`output` 位置参数决定 point_map.json 的落盘位置，文件路径会写成相对该目录的相对路径。注入到编译脚本的预处理命令模板在 `apply_trace_scaffold.sh` 中被明确标注为“示意占位符”，需要使用者按自己仓库的变量名（如 SCRIPTS_PATH、BUILD_OUT_PATH、proj_name）改写，这是主要的集成期配置点。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py:L120–L124](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py#L120-L124), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/apply_trace_scaffold.sh:L20–L26](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/apply_trace_scaffold.sh#L20-L26)
+
+<!-- kb:knowledge owner=feature-ascend-trace-preprocessor facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证入口**
+
+所示的验证入口是集成层面的 `verify_trace_scaffold.py`：`apply_trace_scaffold.sh` 在部署工具链并 patch 编译脚本后调用它（参数 --build-dir、--compile-script）确认脚手架就位；`patch_build_pipeline.py` 自身通过 START/END marker 实现幂等并在重复运行时输出 "no change (hook already exists)"。trace_preprocessor.py 的单元测试未在所示文件中出现。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/apply_trace_scaffold.sh:L28–L33](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/apply_trace_scaffold.sh#L28-L33), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/patch_build_pipeline.py:L32–L34](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/patch_build_pipeline.py#L32-L34)
+
+<!-- kb:knowledge owner=feature-ascend-trace-preprocessor facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**CLI 与公开方法**
+
+trace_preprocessor.py 提供 CLI：`src`（源文件或目录）、`output`（point_map.json 输出目录）、可选 `--modify`（改写源文件）。main 在 src 既不是文件也不是目录时记录错误并以退出码 1 结束；仅在本次运行收集到至少一个点时才调用 save_mappings（这是 main 的行为，save_mappings 本身被调用时无条件写文件，包括空映射）。TracePreprocessor.process_file 对每个匹配返回点信息；当 point_id 超过上限 0xFFFFFFFF 时记录错误并返回空列表。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py:L115–L135](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py#L115-L135), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py:L53–L57](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py#L53-L57), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py:L95–L106](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py#L95-L106)
+
+<!-- kb:knowledge owner=feature-ascend-trace-preprocessor facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**职责与数据流**
+
+TracePreprocessor 维护跨文件共享的 event_map（label→event_id）、point_map（point_id→元数据）和 point_to_event；process_directory 用 os.walk 遍历 C/C++ 源文件并逐个调用 process_file。每个 TRACE_POINT("label","B/E") 匹配按处理顺序递增分配 point_id（上限 0xFFFFFFFF，使用 Python int，并非严格的有符号 int32），相同 label 复用同一 event_id；--modify 时从后向前把调用替换为 point_id 数字，避免偏移失效。save_mappings 把 point_map 写成 point_map.json，键为字符串化的 point_id，文件路径存为相对输出目录的路径。集成侧由 apply_trace_scaffold.sh 串联 bootstrap、patch_build_pipeline.py（把预处理命令注入编译脚本）和 verify_trace_scaffold.py。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py:L20–L26](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py#L20-L26), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py:L48–L66](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py#L48-L66), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py:L87–L106](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py#L87-L106), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/apply_trace_scaffold.sh:L17–L31](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/apply_trace_scaffold.sh#L17-L31)
+
+<!-- kb:knowledge owner=feature-ascend-trace-preprocessor facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的行为**
+
+工具可独立运行：直接对一个文件或目录扫描 TRACE_POINT 并导出 point_map.json（含 label、文件、行号、event_type、event_id），--modify 时改写源码；apply_trace_scaffold.sh/patch_build_pipeline 只是可选的脚手架集成方式，不是必要依赖。嵌套校验按文档字符串宣称支持（L3–L5），但实现（L68–L75）只对 B/E 做栈匹配，未匹配的 E 或残留的 B 不产生任何失败信号。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py:L115–L135](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py#L115-L135), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py:L68–L75](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py#L68-L75), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/apply_trace_scaffold.sh:L23–L31](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/apply_trace_scaffold.sh#L23-L31)
+
+<!-- kb:knowledge owner=feature-ascend-trace-preprocessor facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**取舍**
+
+Inference / 设计推断（非作者历史意图）：
+
+识别采用正则 TRACE_POINT\s*\(...\) 而非语法解析（L32–L43），实现简单但只覆盖双字符串字面量形式；替换采用按位置逆序替换以保持偏移有效（L77–L83）。ID 分配依赖处理顺序：process_directory 用未排序的 os.walk/files 遍历（L89–L92），跨文件的 point_id 顺序随遍历顺序而定，未在所示代码中保证稳定。这些是对所示实现的描述；无文档说明作者动机。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py:L32–L43](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py#L32-L43), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py:L77–L83](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py#L77-L83), [jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py:L89–L92](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ascend-moe-optimizer-auto-trace/scripts/trace_preprocessor.py#L89-L92)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-audit-integrity-hmac-signing.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-audit-integrity-hmac-signing.md
new file mode 100644
index 00000000..49f0a3a1
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-audit-integrity-hmac-signing.md
@@ -0,0 +1,40 @@
+---
+title: "符号审计完整性 HMAC 签名与信任验证（audit_integrity.py）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/audit_integrity.py:L654-L663, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/audit_integrity.py:L122-L154, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/audit_integrity.py:L681-L693, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/audit_integrity.py:L135-L154, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/audit_integrity.py:L466-L490, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/audit_integrity.py:L484-L490, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/audit_integrity.py:L235-L258, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/audit_integrity.py:L593-L623]
+feature: "audit-integrity-hmac-signing"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/audit_integrity.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/audit_integrity.py"]
+---
+
+# 符号审计完整性 HMAC 签名与信任验证（audit_integrity.py）
+
+<!-- kb:knowledge owner=feature-audit-integrity-hmac-signing facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**密钥来源与命令行参数**
+
+通用参数 `--repo-root`（必填）、`--signing-key-env`（默认 `PROJECT_MAINTAINER_AUDIT_SIGNING_KEY`）、`--key-id`（默认 `project-maintainer-local-v1`）、`--strict`；`--audit-map` 对 promote/verify/report 必填（L654–L663）。签名密钥优先取环境变量，只要其值为假值（包括空字符串）就回退到工件内密钥文件 `.doc_project_maintainer/project/audit-signing-key.json`，该文件不存在时自动生成 `secrets.token_urlsafe(32)` 的 hmac-sha256 密钥（L43、L122–L154）。verify/report 还有 `--batch-reuse-threshold`（默认 1）、`--scope`（默认 `default_health_audit`）、`--report-output`、`--require-closure`（L681–L693）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/audit_integrity.py:L654–L663](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/audit_integrity.py#L654-L663), [jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/audit_integrity.py:L122–L154](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/audit_integrity.py#L122-L154), [jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/audit_integrity.py:L681–L693](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/audit_integrity.py#L681-L693)
+
+<!-- kb:knowledge owner=feature-audit-integrity-hmac-signing facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**本地 HMAC 的安全边界**
+
+Inference / 设计推断（非作者历史意图）：
+
+工件内密钥文件与被保护数据同存一处（`.doc_project_maintainer/project/audit-signing-key.json`），且环境变量密钥优先于它（L135–L154）；所示代码没有任何机器或工作区绑定，因此能读到密钥的任何一方都可以用当前脚本重新签名记录。脚本自身哈希检查（`script_hash`）在验证时对比的是当前运行的脚本（L466–L468），其效果是脚本变更后既有 agent 审计的信任被判定失效，而不是阻止修改后的脚本重新签名——`promote` 总是用当前脚本哈希和新 HMAC 覆盖记录（L359、L383–L404）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/audit_integrity.py:L135–L154](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/audit_integrity.py#L135-L154), [jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/audit_integrity.py:L466–L490](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/audit_integrity.py#L466-L490)
+
+<!-- kb:knowledge owner=feature-audit-integrity-hmac-signing facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**校验行为与输入检查**
+
+恒时比较只用于 HMAC 签名（`hmac.compare_digest`，L487–L488）；payload 哈希本身用普通 `!=` 比较（L484）。`promote` 前置校验入口文档：要求存在带内容的 `Actual Role` 标题且文本包含 `health:` 与 `overall:` 字段，并检查源文件与 JSON 输入存在性/结构（L235–L258、L345–L347）。验证报告输出状态计数、信任计数、closure 统计、批复用明细与逐记录 `records_detail`，并由 `recommended_action` 给出建议动作（L593–L623、L638–L651）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/audit_integrity.py:L484–L490](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/audit_integrity.py#L484-L490), [jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/audit_integrity.py:L235–L258](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/audit_integrity.py#L235-L258), [jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/audit_integrity.py:L593–L623](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/audit_integrity.py#L593-L623)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-audit-report-html-renderer.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-audit-report-html-renderer.md
new file mode 100644
index 00000000..2bf52ef3
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-audit-report-html-renderer.md
@@ -0,0 +1,56 @@
+---
+title: "自包含审计可视化 HTML 报告生成器（render_audit_report.py）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py:L546-L555, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py:L22-L39, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py:L82-L112, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py:L147-L176, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py:L462-L505, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py:L42-L53, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py:L531-L543, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py:L365-L371, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py:L217-L247, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py:L512-L528, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py:L188-L216, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py:L318-L362]
+feature: "audit-report-html-renderer"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py"]
+---
+
+# 自包含审计可视化 HTML 报告生成器（render_audit_report.py）
+
+<!-- kb:knowledge owner=feature-audit-report-html-renderer facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**命令行入口与错误契约**
+
+组件以 CLI 脚本暴露：必填位置参数 `repo_root`，输出为单个自包含 HTML 文件；成功时向 stdout 打印 `{"output": <路径>}` 并返回 0（render_audit_report.py:546-555）。输入读取失败（文件缺失、JSON 非法、非对象）统一抛 `AuditReportError`，main 捕获后写入 stderr 并返回退出码 1（22-39, 549-553）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py:L546–L555](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py#L546-L555), [jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py:L22–L39](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py#L22-L39)
+
+<!-- kb:knowledge owner=feature-audit-report-html-renderer facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**风险评分与交互式报告视图**
+
+每个符号经 `normalize_symbol` 合并审计数据与完整性记录，`priority_score` 按信任失败码（如 integrity_mismatch 记 1000）、问题严重度（critical 900…low 200）、审计状态与健康度取最大值定分，映射 high/medium/low/none 风险并生成 dangerReason 与 suggestedAction（82-112, 147-176）。生成的单文件 HTML 内嵌模型 JSON 与原生 JS，提供 scope 切换、搜索、风险/状态过滤、可点击排序的明细表、top-10 优先视图和按源码路径的 scope 树（462-505）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py:L82–L112](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py#L82-L112), [jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py:L147–L176](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py#L147-L176), [jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py:L462–L505](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py#L462-L505)
+
+<!-- kb:knowledge owner=feature-audit-report-html-renderer facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**CLI 参数、默认值与覆盖顺序**
+
+`repo_root` 是必填位置参数，没有默认值；其余文件路径默认挂在 `<repo_root>/.doc_project_maintainer/project/` 下（coverage-map.json、symbol-audit-map.json、audit-integrity-report.json、audit-report.html），可分别用 `--coverage-map/--audit-map/--integrity-report-output/--output/--artifact-root` 覆盖。`--scope` 仅接受 default_health_audit 或 all，默认前者；`--skip-integrity-refresh` 为开关；`--signing-key-env` 默认 `PROJECT_MAINTAINER_AUDIT_SIGNING_KEY`，`--batch-reuse-threshold` 默认 1，两者仅透传给完整性子进程。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py:L42–L53](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py#L42-L53), [jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py:L531–L543](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py#L531-L543)
+
+<!-- kb:knowledge owner=feature-audit-report-html-renderer facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**自包含单文件与部分失败隔离**
+
+Inference / 设计推断（非作者历史意图）：
+
+选择单文件自包含 HTML：模型 JSON 经 `safe_json_for_script` 转义 `< > &` 后内嵌 `<script>`，前端渲染再统一 `escapeHtml`，无需服务器即可离线交互（328-371, 423-428, 456-492）。代价是完整性刷新的失败隔离只做了一半：子进程非零退出或输出非法 JSON 时继续生成报告并把状态行标为 warning（502-504），此时 integrity_report 为 None，查表为空，所有符号的 trustResult 默认 "unverified"、closureEligible 为 false（179-185, 167-169）——即降级为未验证而非使用旧数据；且 `subprocess.run` 本身未捕获启动异常（217-223）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py:L365–L371](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py#L365-L371), [jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py:L217–L247](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py#L217-L247), [jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py:L147–L176](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py#L147-L176)
+
+<!-- kb:knowledge owner=feature-audit-report-html-renderer facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**职责与数据流：JSON 工件到单文件 HTML**
+
+该脚本是 Project Maintainer 技能内的独立 CLI 渲染器，职责边界清晰：不产出审计数据，只消费既有 JSON 工件。数据流为：`generate_report` 先解析路径并读取 coverage-map.json 与 symbol-audit-map.json（512-516），随后可选地以子进程方式调用同目录的 `audit_integrity.py report` 刷新完整性报告（188-216），再把符号记录与完整性记录按 id 合并、评分，组装为 schema 为 `project-maintainer.audit-visual-report.v1` 的模型（147-176, 318-362），最后经 `safe_json_for_script` 转义后内嵌到无外部依赖的 HTML/JS 模板中写出（374-376, 512-528）。交互层（scope 切换、过滤、排序、scope 树）全部由内嵌原生 JS 在浏览器端完成，Python 侧不做请求处理。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py:L512–L528](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py#L512-L528), [jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py:L188–L216](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py#L188-L216), [jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py:L318–L362](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/project-maintainer/scripts/render_audit_report.py#L318-L362)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-cross-channel-history-search-skill.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-cross-channel-history-search-skill.md
new file mode 100644
index 00000000..18707667
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-cross-channel-history-search-skill.md
@@ -0,0 +1,64 @@
+---
+title: "Cross-Channel Session History Search Skill (search_history.py)"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L301-L329, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L258-L298, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L318-L334, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L341-L362, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L82-L89, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L195-L200, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L219-L251, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L142-L157, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L187-L192, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L326-L326, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L381-L397, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L272-L298, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L329-L343, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L219-L230, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L229-L251]
+feature: "cross-channel-history-search-skill"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py"]
+---
+
+# Cross-Channel Session History Search Skill (search_history.py)
+
+<!-- kb:knowledge owner=feature-cross-channel-history-search-skill facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**CLI Entry Point and Invocation Contract**
+
+The skill is a standalone Python CLI (`main()`, exit code 0) run via `python search_history.py`. Public inputs are argparse flags: `--sessions-root`, `--channel`, `--session-id`, `--query` (space-separated keywords, all must match), repeatable `--keyword`, `--start`/`--end`/`--at` time expressions, `--window-minutes`, `--timezone`, `--limit`, `--max-sessions`, and `--auto-expand`/`--no-auto-expand`. Output is not structured data but a fixed-marker plain-text report on stderr (SKILL id line, `HISTORY_SEARCH_SUMMARY_BEGIN/END` block, then `HISTORY_CONTEXT_BLOCK_BEGIN/END` with numbered hits), designed to be greppable in `mcp_exec_command` echo/logs.
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L301–L329](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py#L301-L329), [jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L258–L298](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py#L258-L298)
+
+<!-- kb:knowledge owner=feature-cross-channel-history-search-skill facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**Flags, Defaults and Precedence**
+
+Documented defaults: `--window-minutes` 120, `--timezone` Asia/Shanghai, `--limit` 20, `--max-sessions` 200, `--auto-expand` true (disable with `--no-auto-expand`). Time window precedence: explicit `--start`/`--end` (a missing side defaults to now-24h / now) wins over `--at` (center ± window/2); with none, the last 24 hours is used. Sessions-root precedence: CLI flag, then `get_agent_sessions_dir()` from jiuwenswarm, then `JIUWENSWARM_DATA_DIR/agent/sessions`, then `~/.jiuwenswarm/agent/sessions`. Without `zoneinfo`, timezone falls back to a fixed UTC+8.
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L318–L334](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py#L318-L334), [jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L341–L362](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py#L341-L362), [jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L82–L89](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py#L82-L89)
+
+<!-- kb:knowledge owner=feature-cross-channel-history-search-skill facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**Read-only CLI scan over per-session history.json files**
+
+The skill is a standalone Python CLI whose single flow is: argparse parsing → timezone/time-window resolution → enumerate session directories → read each directory's history.json → filter records by time, non-empty content and keywords → sort by timestamp descending → emit a fixed-marker plain-text report on stderr. Channel filtering matches either a session-id prefix `{channel}_` or an exact equality with the channel; an explicit `--session-id` takes precedence over the channel filter. Malformed files are skipped, but a history.json that is a JSON list containing dicts keeps its dict items even when some entries are non-dicts.
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L195–L200](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py#L195-L200), [jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L219–L251](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py#L219-L251), [jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L142–L157](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py#L142-L157)
+
+<!-- kb:knowledge owner=feature-cross-channel-history-search-skill facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**Cross-channel keyword/time search with capped scan and 72h auto-retry**
+
+The script searches session folders under the resolved sessions root, but only the most recently modified `--max-sessions` directories (default 200) are scanned; older sessions are silently out of scope. When the initial search yields no hits and auto-expand is enabled (default) and neither `--start` nor `--end` was given, the window is replaced with the 72 hours ending at now and the search reruns — note this replaces rather than widens an `--at`-centered window. Hits carry session_id, role, channel_id, timestamp and request_id.
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L187–L192](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py#L187-L192), [jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L326–L326](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py#L326-L326), [jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L381–L397](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py#L381-L397)
+
+<!-- kb:knowledge owner=feature-cross-channel-history-search-skill facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**Self-describing stderr report; no tests shown**
+
+The script's only built-in verification surface is its report: when it reaches emission it prints the `SKILL=cross-channel-history-retrieval` marker plus a `HISTORY_SEARCH_SUMMARY_BEGIN/END` block with timezone, window, filters, scanned_sessions, scanned_records, hit_count and auto_expanded, followed by a numbered hits block. However, reaching the report is not guaranteed — argument parsing, ZoneInfo lookup and time parsing run before it and can fail — and scanned_sessions is incremented before checking for history.json, so the counters alone do not prove session data was actually read. No test entry points for this skill appear in the shown inputs.
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L272–L298](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py#L272-L298), [jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L329–L343](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py#L329-L343), [jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L219–L230](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py#L219-L230)
+
+<!-- kb:knowledge owner=feature-cross-channel-history-search-skill facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**Bounded substring scan with capped output, at the cost of recall and silence on errors**
+
+Inference / 设计推断（非作者历史意图）：
+
+The skill trades index-free simplicity for bounded work: session directories are sorted by mtime and only the newest `--max-sessions` (default 200) are scanned, records are filtered by case-insensitive all-keyword substring match on `content`, hits are sorted by timestamp descending and truncated to `--limit`, and unreadable or non-JSON history.json files are silently skipped rather than reported. The cost is recall: older sessions fall out of scope, records without a parseable timestamp or with blank content are skipped before keyword matching, and no error surfaces for corrupt files. A default 72-hour auto-expand retry (only when no `--start`/`--end` was given and the first pass found nothing) trades a second full scan for better recall on empty results.
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L187–L192](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py#L187-L192), [jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L142–L157](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py#L142-L157), [jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L229–L251](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py#L229-L251), [jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py:L381–L397](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/cross-channel-history-retrieval/scripts/search_history.py#L381-L397)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-daily-report-skill.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-daily-report-skill.md
new file mode 100644
index 00000000..c8737ecf
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-daily-report-skill.md
@@ -0,0 +1,46 @@
+---
+title: "进阶版日报/周报/月报生成器 Skill（advanced-daily-report）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/generators/report_generator.py:L63-L111, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/run_report.py:L501-L546, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/collectors/__init__.py:L13-L28, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/run_report.py:L71-L89, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/run_report.py:L162-L190, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/analyzers/ai_analyzer.py:L104-L139, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/analyzers/ai_analyzer.py:L141-L195, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/analyzers/ai_analyzer.py:L244-L247, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/generators/report_generator.py:L94-L111, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/run_report.py:L735-L775, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/generators/report_generator.py:L484-L506, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/generators/report_generator.py:L21-L25, "openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/开发实践/JiuwenSwarm日报生成器开发实践.md:L276-L295"]
+feature: "daily-report-skill"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/generators/__init__.py", "jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/generators/report_generator.py", "jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/run_report.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/generators/__init__.py", "jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/generators/report_generator.py", "jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/run_report.py", "jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/analyzers/ai_analyzer.py", "jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/collectors/email_collector.py", "jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/collectors/git_collector.py", "jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/collectors/__init__.py", "jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/collectors/aggregator.py", "jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/report_helper.py", "jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/collectors/todo_collector.py", "jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/analyzers/work_analyzer.py"]
+---
+
+# 进阶版日报/周报/月报生成器 Skill（advanced-daily-report）
+
+<!-- kb:knowledge owner=feature-daily-report-skill facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**分层结构与双实现路径**
+
+包结构按文档分为三层：collectors（Git/Email/Memory/Todo 采集器 + DataAggregator 聚合）、analyzers（WorkAnalyzer 工作分析、AIAnalyzer 智能分析）、generators（ReportGenerator 渲染日报/周报/月报）；ReportGenerator.generate_daily 的控制流是 collect → work_analyzer.analyze → 可选 _run_ai_analysis → 渲染 Markdown。独立脚本 run_report.py 绕过 DataAggregator/WorkAnalyzer/ReportGenerator 流程，自行用 collect_git_stats、collect_email_stats、解析记忆与 todo.md 拼装报告，但它仍复用分析层：从 analyzers.ai_analyzer 导入 AIAnalyzer 并调用 analyze_full。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/generators/report_generator.py:L63–L111](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/generators/report_generator.py#L63-L111), [jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/run_report.py:L501–L546](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/run_report.py#L501-L546), [jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/collectors/__init__.py:L13–L28](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/collectors/__init__.py#L13-L28)
+
+<!-- kb:knowledge owner=feature-daily-report-skill facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**路径、凭据与 LLM 配置**
+
+AGENT_ROOT 的解析优先级是 jiuwenswarm.common.utils.get_agent_root_dir()，其次 `JIUWENSWARM_DATA_DIR` 环境变量下的 agent/，最后 `JIUWENSWARM_AGENT_ROOT` 或硬编码 `~/.jiuwenswarm/agent`；CONFIG_ENV 同样优先 get_env_file()，否则 `JIUWENSWARM_DATA_DIR/config/.env` 或 `~/.jiuwenswarm/config/.env`（不使用 JIUWENSWARM_AGENT_ROOT 定位 .env）。collect_email_stats 先解析该 .env 中的 EMAIL_ADDRESS/EMAIL_TOKEN，为空时才回退到同名进程环境变量；EMAIL_PROVIDER 初始即为 "163"，.env 缺失时不会触发其环境回退。AIAnalyzer 从 config.yaml 的 ai_analysis 段读取 model_name/api_base/api_key（缺省 glm-4.7 与 bigmodel OpenAI 兼容端点），否则回退到 react 段——model_name 直接取自 react 本身，api_base/api_key 取自 react.model_client_config。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/run_report.py:L71–L89](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/run_report.py#L71-L89), [jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/run_report.py:L162–L190](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/run_report.py#L162-L190), [jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/analyzers/ai_analyzer.py:L104–L139](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/analyzers/ai_analyzer.py#L104-L139)
+
+<!-- kb:knowledge owner=feature-daily-report-skill facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**已实现行为与依赖**
+
+daily 报告聚合 git log 提交统计、IMAP 邮箱统计、记忆文件条目和 todo.md 勾选框任务，并可启用 AIAnalyzer 的智能摘要、明日计划建议与近 7 天工作模式分析；其中工作模式分析（analyze_work_pattern）是纯统计的确定性计算，不调用 LLM。AI 能力的降级行为分路径：generate_summary/suggest_tomorrow 在 LLM 调用返回空时使用模板化 fallback 文本，但 _get_model 对缺少 openjiuwen 依赖或 API Key 会直接抛 RuntimeError（该调用位于 _call_llm 的 try 之外），ReportGenerator._run_ai_analysis 则捕获整个分析过程的异常并返回 None。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/analyzers/ai_analyzer.py:L141–L195](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/analyzers/ai_analyzer.py#L141-L195), [jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/analyzers/ai_analyzer.py:L244–L247](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/analyzers/ai_analyzer.py#L244-L247), [jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/generators/report_generator.py:L94–L111](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/generators/report_generator.py#L94-L111), [jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/run_report.py:L735–L775](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/run_report.py#L735-L775)
+
+<!-- kb:knowledge owner=feature-daily-report-skill facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证入口**
+
+report_generator.py 自带 main() 测试入口：接收 workspace_dir（可选 git_repo）参数构造 DataAggregator 与 ReportGenerator 并调用 generate_daily()，结果通过 logging.info 输出（未配置日志格式，INFO 级默认不显示）；由于模块顶部使用 `from ..analyzers...` 等包相对导入，直接以脚本方式运行该文件会在进入 main() 前失败，需以包内模块方式执行。文档另给出手动 CLI 验证命令（如 `python run_report.py daily --save`）作为端到端流程的检验入口。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/generators/report_generator.py:L484–L506](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/generators/report_generator.py#L484-L506), [jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/generators/report_generator.py:L21–L25](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/advanced-daily-report/generators/report_generator.py#L21-L25), [docs/zh/开发实践/JiuwenSwarm日报生成器开发实践.md:L276–L295](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/docs/zh/%E5%BC%80%E5%8F%91%E5%AE%9E%E8%B7%B5/JiuwenSwarm%E6%97%A5%E6%8A%A5%E7%94%9F%E6%88%90%E5%99%A8%E5%BC%80%E5%8F%91%E5%AE%9E%E8%B7%B5.md#L276-L295)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-deepsearch-research-pipeline.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-deepsearch-research-pipeline.md
new file mode 100644
index 00000000..5cea19ed
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-deepsearch-research-pipeline.md
@@ -0,0 +1,22 @@
+---
+title: "openJiuwen-DeepSearch 深度研究执行管线"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/openJiuwen-DeepSearch/scripts/main.py:L200-L230, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/openJiuwen-DeepSearch/scripts/main.py:L293-L339, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/openJiuwen-DeepSearch/scripts/main.py:L233-L258]
+feature: "deepsearch-research-pipeline"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/openJiuwen-DeepSearch/scripts/main.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/openJiuwen-DeepSearch/scripts/main.py", "jiuwenswarm/resources/agent/workspace/skills/openJiuwen-DeepSearch/scripts/validate_environment.py", "jiuwenswarm/resources/agent/workspace/skills/openJiuwen-DeepSearch/scripts/convert_docx.py", "jiuwenswarm/resources/agent/workspace/skills/openJiuwen-DeepSearch/scripts/convert_html.py", "jiuwenswarm/resources/agent/workspace/skills/openJiuwen-DeepSearch/scripts/verify_skill_structure.py"]
+---
+
+# openJiuwen-DeepSearch 深度研究执行管线
+
+<!-- kb:knowledge owner=feature-deepsearch-research-pipeline facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**入口与调用契约**
+
+命令行入口 `main.py --mode query --query "题目" [--background|--foreground]`，`--mode` 仅支持 `query`，`--query` 默认为 "AI手机研究报告"。`execute_deep_search(query)` 供 Agent 调用，成功返回报告字符串，配置缺失（ValueError）或执行异常时记日志并返回 None；main 据此以退出码 0/1 结束。未指定 `--foreground` 时默认走后台模式：父进程以 `JIUWEN_BACKGROUND_MODE=1` 重新拉起分离的子进程并写 PID.info 后退出；若环境已是 `JIUWEN_BACKGROUND_MODE=1`，run_background 直接返回，由 main 继续前台执行研究。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/openJiuwen-DeepSearch/scripts/main.py:L200–L230](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/openJiuwen-DeepSearch/scripts/main.py#L200-L230), [jiuwenswarm/resources/agent/workspace/skills/openJiuwen-DeepSearch/scripts/main.py:L293–L339](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/openJiuwen-DeepSearch/scripts/main.py#L293-L339), [jiuwenswarm/resources/agent/workspace/skills/openJiuwen-DeepSearch/scripts/main.py:L233–L258](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/openJiuwen-DeepSearch/scripts/main.py#L233-L258)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-docx-pro-cli.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-docx-pro-cli.md
new file mode 100644
index 00000000..e3e7e8c8
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-docx-pro-cli.md
@@ -0,0 +1,54 @@
+---
+title: "docx-pro Word 文档操作 CLI"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_pro.py:L31-L41, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/renderer.py:L583-L599, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_replace.py:L221-L253, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_pro.py:L3-L12, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_replace.py:L5-L26, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/setup_check.py:L9-L26, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_pro.py:L331-L347, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_pro.py:L404-L421, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_pro.py:L176-L178, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_pro.py:L277-L326, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_replace.py:L174-L205, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_replace.py:L264-L274, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/renderer.py:L233-L252, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_replace.py:L284-L331, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_pro.py:L183-L216]
+feature: "docx-pro-cli"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_pro.py", "jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/setup_check.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_pro.py", "jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/setup_check.py", "jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_replace.py", "jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/renderer.py", "jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/md_export.py"]
+---
+
+# docx-pro Word 文档操作 CLI
+
+<!-- kb:knowledge owner=feature-docx-pro-cli facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**分层结构与数据流**
+
+docx_pro.py 是编排层：解析参数、校验路径，把工作委托给同目录的四个模块——renderer.py（大纲字典渲染为 docx）、md_parser.parse_markdown（Markdown→大纲）、md_export.docx_to_markdown（docx→Markdown）、docx_replace.replace_in_docx（保真替换）；通过 `sys.path.append` 引入同目录模块。create 与 from-md 共用 renderer 的 `render_outline(outline, out)` 统一渲染管线；replace 走独立的纯标准库 zip/XML 路径，不经过 python-docx 写入。renderer 内部按 `BLOCK_RENDERERS` 字典把块 type 分派到具体渲染函数。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_pro.py:L31–L41](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_pro.py#L31-L41), [jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/renderer.py:L583–L599](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/renderer.py#L583-L599), [jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_replace.py:L221–L253](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_replace.py#L221-L253)
+
+<!-- kb:knowledge owner=feature-docx-pro-cli facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的行为与依赖**
+
+生成侧支持封面、目录域（Word 中按 F9 更新）、多级标题（映射到内置 Heading 样式供 TOC/导航识别）、表格（跨行跨列合并、斑马纹、列宽）、图片、代码块、引用、页眉页脚页码、每页 VML 文字水印；replace 支持跨 run 定位替换、批量映射（-f/-t 或 --map）、--dry-run，匹配不跨段落/单元格/域代码，重打包时其余 zip 条目按原字节复制。依赖 python-docx（create/转换/检查路径）与 docx_replace 仅用标准库；setup_check.py 提供依赖自检。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_pro.py:L3–L12](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_pro.py#L3-L12), [jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_replace.py:L5–L26](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_replace.py#L5-L26), [jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/setup_check.py:L9–L26](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/setup_check.py#L9-L26)
+
+<!-- kb:knowledge owner=feature-docx-pro-cli facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**子命令入口与退出码契约**
+
+docx_pro.py 通过 argparse 暴露 create/from-md/to-md/replace/inspect/toc/watermark 七个子命令，由 `args.func(args)` 分派；main 统一预检输入文件存在性（不存在返回 2），并把 FileNotFoundError/ValueError 转为退出码 2。覆写保护仅存在于 create（输出不得等于输入 JSON）与 replace（输出不得等于输入 docx，返回 2）；toc 与 watermark 子命令无此检查，直接 `doc.save(args.out)`。replace 的退出码分支不对称：仅当条目列表不一致或出现 unexpected_changes 时返回 1，零命中也返回 1，而 `_verify` 中记录的 opens_ok=False 不会触发失败分支。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_pro.py:L331–L347](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_pro.py#L331-L347), [jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_pro.py:L404–L421](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_pro.py#L404-L421), [jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_pro.py:L176–L178](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_pro.py#L176-L178), [jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_pro.py:L277–L326](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_pro.py#L277-L326)
+
+<!-- kb:knowledge owner=feature-docx-pro-cli facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**保真替换与目录域的实现取舍**
+
+replace_in_xml 跨 run 命中时只把替换文本写入首个命中节点、清空被匹配区间覆盖的中间/尾部节点内容，节点内未被匹配覆盖的文本通过区间拼接保留；回写时若新文本含前导/尾随空白且原标签缺 xml:space 会补上该属性，因此命中部件并非严格字节不变。整包重打包时未修改的 zip 条目按原始字节与原压缩方式复制。目录采用域（field）而非预生成条目：add_toc 插入 TOC 域并留提示文本，由用户在 Word 中按 F9 更新生成（此为代码展示的行为，其设计动机属于推断）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_replace.py:L174–L205](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_replace.py#L174-L205), [jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_replace.py:L264–L274](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_replace.py#L264-L274), [jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/renderer.py:L233–L252](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/renderer.py#L233-L252)
+
+<!-- kb:knowledge owner=feature-docx-pro-cli facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**replace 的后验校验与退出码**
+
+非 dry-run 的 replace 在写出后由 _verify 校验：比较新旧 zip 条目列表是否一致、逐条目字节比对（区分预期修改与 unexpected_changes）、对目标部件做残留计数，并尝试用 python-docx 重新打开两个文件——但 paragraphs/tables 仅记录新旧数量（len 对），代码未比较二者是否相等。退出码：total_found 为 0 时也输出警告日志，dry-run 返回 1，正式替换同样在零命中时返回 1；条目列表不一致或出现 unexpected_changes 也返回 1。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_replace.py:L284–L331](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_replace.py#L284-L331), [jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_pro.py:L183–L216](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/docx-pro/scripts/docx_pro.py#L183-L216)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-financial-document-parser.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-financial-document-parser.md
new file mode 100644
index 00000000..fcffe32b
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-financial-document-parser.md
@@ -0,0 +1,64 @@
+---
+title: "财务文档解析 Skill（financial_parser.py）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L508-L518, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L552-L558, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L78-L103, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L411-L439, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L507-L554, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L82-L133, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L174-L231, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L367-L409, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L17-L29, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L45-L76, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L521-L525, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L105-L172, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L390-L409, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L441-L504, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L127-L129, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L212-L218, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L404-L409]
+feature: "financial-document-parser"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py"]
+---
+
+# 财务文档解析 Skill（financial_parser.py）
+
+<!-- kb:knowledge owner=feature-financial-document-parser facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证入口**
+
+所示代码中没有测试；文件自带 `if __name__ == '__main__': main()` 入口，可通过 CLI 对样例文件手工验证（epilog 中列了 invoice.pdf/receipt.jpg/statement.csv 示例），`--format json` 便于检查结构化字段。错误路径（缺文件、不支持格式、缺依赖）会以 stderr 消息和退出码 1 显现。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L508–L518](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py#L508-L518), [jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L552–L558](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py#L552-L558)
+
+<!-- kb:knowledge owner=feature-financial-document-parser facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**公共入口与输出契约**
+
+组件提供两层入口。库层为 `FinancialParser(file_path)`，核心方法是 `parse()`，返回 `FinancialDocument` 数据类；实例方法 `to_dict()`/`to_json()`/`to_csv()`/`to_markdown()` 提供四种导出，`to_csv()` 未指定路径时默认写回源文件同名的 .csv。CLI 层为 `main()`：位置参数 `file`，`--format/-f`（markdown/json/csv/all，默认 markdown）、`--output/-o`（仅 csv 用）、`--quiet/-q`。处理块（构造、parse、导出）内的异常被捕获并打印到 stderr 后以退出码 1 结束；参数解析本身在 try 块之外。缺失依赖的行为按输入类型区分：图片缺 OCR 依赖时抛 ImportError，扫描版 PDF 缺 OCR 时静默跳过 OCR，CSV 不依赖任何可选库。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L78–L103](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py#L78-L103), [jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L411–L439](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py#L411-L439), [jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L507–L554](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py#L507-L554)
+
+<!-- kb:knowledge owner=feature-financial-document-parser facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**解析管线与数据流**
+
+`parse()` 按文件后缀分派：PDF 走 pdfplumber 提取文本与表格（无文本且具备 OCR 依赖时对扫描件做 Tesseract OCR），图片走 OCR，CSV 用 DictReader 逐行读入并求和为 Statement；随后统一执行后处理——`_detect_doc_type()` 关键词判定类型、`_categorize_items()` 关键词分类、`_generate_insights()` 生成洞察与标记。字段提取是混合策略：发票号、供应商、日期、金额、税额用多组正则（首个匹配生效），货币用子串检查（USD/EUR/CNY 符号），PDF 表格则按表头关键词定位描述/数量/单价/金额列后取数。未提取到小计时按 total/tax 推算。结果最终由 to_* 方法渲染为报告。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L82–L133](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py#L82-L133), [jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L174–L231](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py#L174-L231), [jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L367–L409](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py#L367-L409)
+
+<!-- kb:knowledge owner=feature-financial-document-parser facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**配置面**
+
+该脚本没有配置文件或环境变量，可调项只有 CLI 参数（`--format`、`--output`、`--quiet`）和代码内的类级常量：`CATEGORY_KEYWORDS` 定义八个费用类别及其中英文关键词（Software/Office/Travel/Meals/Utilities/Marketing/Professional/Equipment），未命中关键词的行项目归为 "Other"。运行时能力由可选依赖的导入探测决定：pdfplumber 与 pdf2image+pytesseract 分别以 try/except 探测，`FinancialDocument` 的默认值（currency="CNY"、各金额 0.0）构成隐含行为基线。洞察逻辑中的大额阈值 10000 也是硬编码。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L17–L29](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py#L17-L29), [jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L45–L76](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py#L45-L76), [jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L521–L525](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py#L521-L525)
+
+<!-- kb:knowledge owner=feature-financial-document-parser facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的行为**
+
+支持三类输入：PDF（文本层提取 + 表格提取，文本为空且 OCR 可用时回退到 chi_sim+eng OCR）、PNG/JPG/JPEG 图片（OCR，缺依赖时抛 ImportError）、CSV 对账单（识别 描述/description/摘要 与 金额/amount 列）。后处理产出：文档类型判定（Invoice/Receipt/Statement/Expense Report）、行项目费用分类、洞察（最大支出类别、可抵扣税额）与标记（金额超过 10000 的大额交易）。报告输出 Markdown（含明细表、分类汇总、洞察、需关注项）、JSON、CSV（utf-8-sig，含日期/供应商/描述/类别/金额/可抵税列）三种形式。注意：缺 pdfplumber 时 PDF 解析抛 ImportError，但缺 OCR 依赖的扫描版 PDF 不报错而是跳过 OCR 继续提取。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L105–L172](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py#L105-L172), [jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L390–L409](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py#L390-L409), [jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L441–L504](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py#L441-L504)
+
+<!-- kb:knowledge owner=feature-financial-document-parser facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**设计取舍：可选依赖的优雅降级与规则化提取的精度边界**
+
+Inference / 设计推断（非作者历史意图）：
+
+解析器以可选依赖探测换取部署便利：pdfplumber 与 pdf2image+pytesseract 在导入期用 try/except 探测（L17-L29），缺 pdfplumber 解析 PDF 会抛 ImportError，但扫描版 PDF 在无 OCR 依赖时不报错而是静默跳过 OCR 继续（L127-L129、L137-L138），代价是文本层为空的扫描件会以空 raw_text 走完后续流程。字段提取采用规则化正则/关键词而非模型：发票号、日期、金额等各维护多组模式以覆盖常见中英文版式（如 L181-L186、L212-L218、L234-L240），但未覆盖的格式变化可能漏提；规则中的阈值与展示也偏硬编码——大额交易固定以 10000 判定（L404-L405），Markdown 报告的金额一律以 ¥ 前缀渲染（L451、L464、L470-L472），与 L226-L231 可能识别出的 USD/EUR 币种不一致。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L17–L29](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py#L17-L29), [jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L127–L129](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py#L127-L129), [jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L212–L218](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py#L212-L218), [jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py:L404–L409](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/financial-document-parser/financial_parser.py#L404-L409)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-github-issue-feedback-script.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-github-issue-feedback-script.md
new file mode 100644
index 00000000..105885f8
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-github-issue-feedback-script.md
@@ -0,0 +1,64 @@
+---
+title: "GitHub Issue 反馈创建脚本（open_github_issue.py）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/gitcode-api/scripts/open_github_issue.py:L18-L55, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/gitcode-api/scripts/open_github_issue.py:L1-L50, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/gitcode-api/scripts/open_github_issue.py:L11-L37, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/gitcode-api/scripts/open_github_issue.py:L3-L50, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/gitcode-api/scripts/open_github_issue.py:L18-L37, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/gitcode-api/scripts/open_github_issue.py:L48-L55, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/gitcode-api/scripts/open_github_issue.py:L31-L37, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/gitcode-api/scripts/open_github_issue.py:L13-L13, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/gitcode-api/scripts/open_github_issue.py:L48-L51]
+feature: "github-issue-feedback-script"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/gitcode-api/scripts/open_github_issue.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/gitcode-api/scripts/open_github_issue.py"]
+---
+
+# GitHub Issue 反馈创建脚本（open_github_issue.py）
+
+<!-- kb:knowledge owner=feature-github-issue-feedback-script facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**CLI 入口与契约**
+
+脚本提供单一 CLI 入口 `main(argv)`，返回进程退出码：参数为位置参数 `title`（议题标题）和必填选项 `--body`（议题正文）；另有可重复的 `--label`（收集为 `labels` 列表）、`--owner`、`--repo`、`--api-key` 选项。成功时通过 `gh.rest(version="2026-03-10").issues.create(**payload)` 创建议题并打印 `resp.parsed_data`，返回 0；缺少 GitHub 令牌时向 stderr 输出 `GITHUB_ACCESS_TOKEN is not set` 并返回 1。`__main__` 块通过 `raise SystemExit(main())` 暴露为可执行脚本。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/gitcode-api/scripts/open_github_issue.py:L18–L55](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/gitcode-api/scripts/open_github_issue.py#L18-L55)
+
+<!-- kb:knowledge owner=feature-github-issue-feedback-script facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**职责与数据流**
+
+脚本位于 agent workspace 的 `skills/gitcode-api/scripts/` 目录，作为技能脚本被组织，职责单一：解析 CLI 参数 → 解析令牌 → 组装 payload dict（owner/repo/title/body，labels 仅在提供时加入）→ 调用 githubkit 的 `GitHub(auth=token)` REST 客户端创建议题 → 打印解析后的响应。它是薄封装层，议题创建逻辑全部委托给 `githubkit` 库，自身不含重试、分页或其他编排。`output_content = partial(print)` 是对输出的单一间接点。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/gitcode-api/scripts/open_github_issue.py:L1–L50](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/gitcode-api/scripts/open_github_issue.py#L1-L50)
+
+<!-- kb:knowledge owner=feature-github-issue-feedback-script facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**设置项与优先级**
+
+默认目标仓库为 owner `Trenza1ore`、repo `GitCode-API`，可通过 `--owner`/`--repo` 覆盖；REST API 版本固定为常量 `API_VERSION = "2026-03-10"`，不可通过 CLI 配置。令牌解析优先级：环境变量 `GITHUB_ACCESS_TOKEN` 优先于 `--api-key` 参数，两者皆空时以退出码 1 终止。`--body` 虽有 `default=""` 但被标记为 `required=True`。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/gitcode-api/scripts/open_github_issue.py:L11–L37](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/gitcode-api/scripts/open_github_issue.py#L11-L37)
+
+<!-- kb:knowledge owner=feature-github-issue-feedback-script facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的行为**
+
+支持在指定 GitHub 仓库创建带标题、正文和任意多个标签的议题（标签通过重复 `--label` 传入）。外部依赖为 `githubkit`（提供 `GitHub` 客户端与 REST API 版本化调用），令牌来自环境或 CLI。按目录命名推断，该脚本服务于 GitCode-API 技能，用于以 GitHub 议题形式提交反馈。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/gitcode-api/scripts/open_github_issue.py:L3–L50](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/gitcode-api/scripts/open_github_issue.py#L3-L50)
+
+<!-- kb:knowledge owner=feature-github-issue-feedback-script facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证方式**
+
+在本次展示的部分输入中，该脚本自身没有附带测试：文件仅 55 行，除 `main()` 和 `__main__` 入口外无其他可执行入口，也未引用任何测试框架。可观察的验证路径是手动执行 CLI——缺少令牌时会向 stderr 打印 `GITHUB_ACCESS_TOKEN is not set` 并返回退出码 1，成功创建时打印 `resp.parsed_data` 并返回 0；不在本次展示中的仓库其他位置的测试无法排除。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/gitcode-api/scripts/open_github_issue.py:L18–L37](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/gitcode-api/scripts/open_github_issue.py#L18-L37), [jiuwenswarm/resources/agent/workspace/skills/gitcode-api/scripts/open_github_issue.py:L48–L55](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/gitcode-api/scripts/open_github_issue.py#L48-L55)
+
+<!-- kb:knowledge owner=feature-github-issue-feedback-script facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**Design Tradeoffs**
+
+Inference / 设计推断（非作者历史意图）：
+
+Token resolution prefers environment variable `GITHUB_ACCESS_TOKEN` over the `--api-key` CLI option; when both are empty, the script prints `GITHUB_ACCESS_TOKEN is not set` to stderr and returns exit code 1. This allows the script to run in environments with injected credentials while keeping the CLI option as a fallback (the specific benefit is inference). The script is a thin wrapper that delegates the entire issue-creation call to githubkit's `GitHub(auth=token)` client with a fixed version constant `API_VERSION = "2026-03-10"`, printing `resp.parsed_data` on success; the only explicit error handling is the missing token check, and API-call exceptions are not caught (cost is inference; no documentary evidence of the author's intent is shown).
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/gitcode-api/scripts/open_github_issue.py:L31–L37](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/gitcode-api/scripts/open_github_issue.py#L31-L37), [jiuwenswarm/resources/agent/workspace/skills/gitcode-api/scripts/open_github_issue.py:L13–L13](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/gitcode-api/scripts/open_github_issue.py#L13-L13), [jiuwenswarm/resources/agent/workspace/skills/gitcode-api/scripts/open_github_issue.py:L48–L51](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/gitcode-api/scripts/open_github_issue.py#L48-L51)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-huawei-maas-apikey-creation.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-huawei-maas-apikey-creation.md
new file mode 100644
index 00000000..658b502d
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-huawei-maas-apikey-creation.md
@@ -0,0 +1,46 @@
+---
+title: "华为云 MaaS API Key 自动创建与捕获（auto_create_apikey）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_create_apikey.py:L207-L238, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_create_apikey.py:L363-L406, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_create_apikey.py:L240-L331, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/lib/huawei_selectors.py:L34-L66, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_create_apikey.py:L356-L370, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_create_apikey.py:L380-L404, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_create_apikey.py:L228-L232, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/lib/huawei_selectors.py:L93-L108, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_create_apikey.py:L81-L83, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_create_apikey.py:L250-L260, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_create_apikey.py:L315-L330, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_create_apikey.py:L399-L406]
+feature: "huawei-maas-apikey-creation"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_create_apikey.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_create_apikey.py", "jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/lib/huawei_selectors.py"]
+---
+
+# 华为云 MaaS API Key 自动创建与捕获（auto_create_apikey）
+
+<!-- kb:knowledge owner=feature-huawei-maas-apikey-creation facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**入口与返回契约**
+
+CLI 入口 `main()` 提供 `--cdp-url`（默认空，回退 `resolve_cdp_url()`）、`--tag`（默认 `jiuwenswarm`）、`--description`（默认 `jiuwenswarm-config`）、`--timeout`（默认 30）、`--json`（已声明）参数，输出结果 JSON 并以 `ok` 字段决定退出码 0/1。核心函数 `auto_create_apikey()` 在 try/except 包裹的主流程内失败时返回 `make_failure(stage, error)` 字典（如 `insufficient_balance`、`create_btn_not_found`），成功返回 `make_success` 附带 `api_key`、`tag`、`dialog_closed`；但后缀生成/日志与 argparse 解析发生在异常处理之外，故并非所有失败路径都走该 JSON 契约。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_create_apikey.py:L207–L238](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_create_apikey.py#L207-L238), [jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_create_apikey.py:L363–L406](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_create_apikey.py#L363-L406)
+
+<!-- kb:knowledge owner=feature-huawei-maas-apikey-creation facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**分层：流程编排与选择器库**
+
+`auto_create_apikey.py` 负责七步流程编排（连接 CDP、导航、点创建按钮、填表、提交、轮询检测、提取 Key），DOM 定位部分委托给 `lib/huawei_selectors.py` 的 `SelectorSet`（CSS 优先、文本兜底），但权限选择（`_select_permission_all`）和页面文本预览等处也直接调用 `page.locator`。`SelectorSet.first_visible` 用于可选/检测类元素的即时快照，`wait_first` 用于必然出现元素的等待，配合 `click_wait_first` 等高层函数。选择"全部"权限失败时保持默认值不中断，关闭弹窗失败仍返回成功（`dialog_closed=false`）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_create_apikey.py:L240–L331](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_create_apikey.py#L240-L331), [jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/lib/huawei_selectors.py:L34–L66](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/lib/huawei_selectors.py#L34-L66), [jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_create_apikey.py:L356–L370](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_create_apikey.py#L356-L370)
+
+<!-- kb:knowledge owner=feature-huawei-maas-apikey-creation facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**可配置项与固定常量**
+
+用户可配置项为 CLI/函数参数：`cdp_url`、`tag`（默认 `jiuwenswarm`）、`description`（默认 `jiuwenswarm-config`）、`timeout_s`（默认 30），另有已声明但未使用的 `--json` 标志。运行时会在 tag/description 后追加 UTC 时间后缀（`YYYYMMDD_HHMMSS`）避免标签重复。目标页面 URL（`MAAS_APIKEY_URL`）、充值链接与实名认证链接是硬编码常量，不通过参数暴露。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_create_apikey.py:L380–L404](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_create_apikey.py#L380-L404), [jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_create_apikey.py:L228–L232](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_create_apikey.py#L228-L232), [jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/lib/huawei_selectors.py:L93–L108](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/lib/huawei_selectors.py#L93-L108)
+
+<!-- kb:knowledge owner=feature-huawei-maas-apikey-creation facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证：运行时可观测性与自检**
+
+所示输入未包含针对该脚本的自动化测试入口，可确认的验证机制是运行时自检与诊断输出：提取的 Key 需通过 _is_plausible_key（非空、长度 ≥30、非纯数字）才算成功，否则返回 extract_failed 并建议手动复制后经 ask_user 填入。失败分支附带诊断线索——如 create_btn_not_found 返回 page_url 与 1500 字符的页面文本预览（_page_text_preview），insufficient_balance/realname_required 分别附带 recharge_url/realname_url；流程通过 emit/emit_progress 输出 0–7 步进度事件，CLI 以结果 ok 字段决定退出码 0/1。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_create_apikey.py:L81–L83](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_create_apikey.py#L81-L83), [jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_create_apikey.py:L250–L260](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_create_apikey.py#L250-L260), [jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_create_apikey.py:L315–L330](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_create_apikey.py#L315-L330), [jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_create_apikey.py:L399–L406](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_create_apikey.py#L399-L406)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-huawei-maas-cdp-authorize.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-huawei-maas-cdp-authorize.md
new file mode 100644
index 00000000..d4e2b368
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-huawei-maas-cdp-authorize.md
@@ -0,0 +1,64 @@
+---
+title: "华为云 MaaS 委托授权自动化（auto_authorize.py）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py:L215-L230, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py:L98-L104, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py:L3-L19, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py:L106-L133, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py:L168-L195, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py:L57-L80, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py:L98-L133, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py:L76-L95, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py:L168-L205, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py:L15-L19, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py:L98-L112]
+feature: "huawei-maas-cdp-authorize"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py"]
+---
+
+# 华为云 MaaS 委托授权自动化（auto_authorize.py）
+
+<!-- kb:knowledge owner=feature-huawei-maas-cdp-authorize facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**入口与输出契约**
+
+脚本以 CLI 方式运行：`python auto_authorize.py --cdp-url http://127.0.0.1:9333 --json`，入口 `main()` 解析 `--cdp-url`、`--timeout`（默认 45 秒）和 `--json` 三个参数。核心函数 `auto_authorize(cdp_url, timeout_s=45)` 返回结果 dict：成功时 `make_success("authorize", ...)` 携带 `auth_done`、`skipped_reason`、`disclaimer_handled`；失败时 `make_failure(stage, error)`，stage 取值包括 `connect_failed`、`navigate_failed`、`click_failed`、`dialog_timeout`、`confirm_not_found`、`success_timeout`、`exception`。进程退出码为 `0`（ok）或 `1`，结果经 `output_json` 输出。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py:L215–L230](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py#L215-L230), [jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py:L98–L104](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py#L98-L104)
+
+<!-- kb:knowledge owner=feature-huawei-maas-cdp-authorize facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**在 Skill 流水线中的位置与控制流**
+
+脚本是 huawei-cloud-maas-setup Skill 的一个步骤，前置依赖 `ensure_browser.py` 启动浏览器并暴露 CDP、`navigate.py` + ask_user 完成用户登录。它通过 `lib.cdp_client.connect_page` 以 Playwright 连接已有浏览器页面，流程为：导航到 MaaS 首页 → 等待 SPA 渲染 → 处理服务声明弹窗 → 检测授权警告 → 点"此处"链接（兜底点警告条本身）→ 确认对话框 → 点"确定" → 等待"权限更新成功"提示。选择器与 URL 常量来自 `lib.huawei_selectors`，结果结构来自 `lib.flow_state`。文档字符串明确约束：不向上层抛异常，失败时返回 `{ok:false, stage:"authorize"}`，由 Skill 决定是否降级为手动模式。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py:L3–L19](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py#L3-L19), [jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py:L106–L133](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py#L106-L133)
+
+<!-- kb:knowledge owner=feature-huawei-maas-cdp-authorize facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证入口**
+
+Inference / 设计推断（非作者历史意图）：
+
+所示文件中未包含针对 auto_authorize 的测试；可见的验证途径是脚本自身的 `--json` 模式：以真实 CDP 浏览器手动运行，通过退出码和输出 dict 中的 `ok`/`stage`/`skipped_reason` 字段核对各阶段结果。实现内部各失败 stage（`connect_failed` 到 `success_timeout`）构成了可观测的分阶段检查点。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py:L215–L230](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py#L215-L230), [jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py:L168–L195](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py#L168-L195)
+
+<!-- kb:knowledge owner=feature-huawei-maas-cdp-authorize facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**配置项与默认值**
+
+CLI 仅有三个参数：`--cdp-url`（默认空字符串）、`--timeout`（int，默认 45，作为 `timeout_s` 传入 `auto_authorize`）和 `--json` 开关。`--cdp-url` 为空时调用 `lib.cdp_client.resolve_cdp_url()` 兜底解析；解析结果仍为空则以 stage `init` 失败、退出码 1。授权警告的判定依赖硬编码的 `#authGlobalMessage` 容器选择器和 `_AUTH_WARNING_KEYWORDS` 关键词元组（如"权限不足"、"尚未授权"等），均不可通过参数配置。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py:L215–L230](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py#L215-L230), [jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py:L57–L80](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py#L57-L80)
+
+<!-- kb:knowledge owner=feature-huawei-maas-cdp-authorize facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的授权自动化行为**
+
+脚本通过 CDP（`connect_page`，15s 超时）接入已登录的浏览器，导航到 MaaS 首页（30s 超时）后完成：处理首次访问的服务声明弹窗（`handle_disclaimer`）、检测授权警告、点击"此处"链接（找不到或点击失败时兜底点击警告元素本身）、等待授权对话框（10s）、点击"确定"（5s）、等待"权限更新成功"提示（15s）。检测逻辑优先读 `#authGlobalMessage` 容器文本匹配关键词；容器不可用时退化为 `SELECTOR_AUTH_WARNING` 选择器快照，仅当回退警告元素的文本读取抛异常时才直接认定存在警告，其余路径未命中即返回 False 并以 `skipped_reason="no_warning"` 视为已授权。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py:L98–L133](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py#L98-L133), [jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py:L76–L95](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py#L76-L95), [jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py:L168–L205](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py#L168-L205)
+
+<!-- kb:knowledge owner=feature-huawei-maas-cdp-authorize facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**设计取舍：降级优先与超时预算**
+
+脚本采用"失败不中断"的折中策略：文档字符串（L15–L18）声明不向上层抛异常、失败时返回 `{ok:false, stage:...}` 由 Skill 决定是否降级为手动模式，理由是用户可能已授权只是检测未识别；但实现中 `auto_authorize` 入口处的 `emit_progress(0, 5, ...)`（L100）在两个 try 块之外，并非所有路径都保证返回结构化结果。另一处权衡是超时预算：docstring 要求整个流程 ≤30s（L19），而各阶段独立超时（导航 30s、对话框 10s、成功提示 15s，L110/L170/L189）加上固定 sleep（2.5s/1.5s/1.0s，用于等 SPA 渲染与动画，与选择器等待并存而非替代）理论上可远超 30s，且 `timeout_s` 参数（默认 45，L98、L218、L228）在函数体内未被使用，文档约束与实现不一致。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py:L15–L19](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py#L15-L19), [jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py:L98–L112](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py#L98-L112), [jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py:L168–L195](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_authorize.py#L168-L195)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-huawei-realname-account-check.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-huawei-realname-account-check.md
new file mode 100644
index 00000000..bd0f9ff1
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-huawei-realname-account-check.md
@@ -0,0 +1,56 @@
+---
+title: "check_account — 华为云账号实名认证状态检测脚本"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/check_account.py:L3-L17, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/check_account.py:L56-L96, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/check_account.py:L110-L128, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/check_account.py:L90-L102, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/lib/huawei_selectors.py:L558-L605, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/check_account.py:L50-L96, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/lib/huawei_selectors.py:L561-L605, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/check_account.py:L50-L82, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/check_account.py:L14-L17]
+feature: "huawei-realname-account-check"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/check_account.py", "jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/lib/huawei_selectors.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/check_account.py", "jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/lib/huawei_selectors.py"]
+---
+
+# check_account — 华为云账号实名认证状态检测脚本
+
+<!-- kb:knowledge owner=feature-huawei-realname-account-check facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**在 Skill 编排流程中的位置与控制流**
+
+脚本是 huawei-cloud-maas-setup Skill 的一个步骤：前置依赖 `ensure_browser.py` 启动浏览器并通过 CDP 暴露、`navigate.py` 已登录费用中心首页；本步骤复用已有 page（不新建标签页、不导航），只做关弹窗和检测，结果供编排层决定 ask_user 文案。控制流为：`connect_page` 接管 CDP → sleep 2s 等 SPA 渲染 → `dismiss_popups`（最多 3 轮）→ `detect_realname_status` → 输出 JSON；`finally` 中 `pw.stop()` 断开 Playwright 连接。选择器与检测逻辑下沉在 `lib/huawei_selectors.py`，流程状态封装在 `lib/flow_state`。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/check_account.py:L3–L17](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/check_account.py#L3-L17), [jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/check_account.py:L56–L96](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/check_account.py#L56-L96)
+
+<!-- kb:knowledge owner=feature-huawei-realname-account-check facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**CLI 入口与结果契约**
+
+公开入口是 `main(argv)`/CLI：`python check_account.py --cdp-url <url> --json`。`--cdp-url` 留空时经 `resolve_cdp_url()` 自动解析；解析不到则输出 JSON 失败结果并返回退出码 1；正常路径总是 `output_json(result)`，退出码 0 当且仅当 `result["ok"]` 为真。成功时结果包含 `cdp_url`、`realname_authenticated`、`popups_closed`、`realname_auth_url` 字段；失败经 `make_failure(stage, error_message, ...)`，观察到的 stage 调用值为 `connect_failed`、`exception`、`init`。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/check_account.py:L110–L128](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/check_account.py#L110-L128), [jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/check_account.py:L90–L102](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/check_account.py#L90-L102)
+
+<!-- kb:knowledge owner=feature-huawei-realname-account-check facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**命令行参数**
+
+argparse 定义三个参数：`--cdp-url`（默认空字符串，留空自动解析）、`--timeout`（int，默认 15，帮助文案称"整体超时秒数"，传入后成为 `check_account` 的 `timeout_s` 形参）、`--json`（store_true 帮助开关）。注意在所示实现中 `args.json` 从未被读取：无论是否传 `--json`，脚本都无条件以 `output_json` 输出 JSON。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/check_account.py:L110–L128](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/check_account.py#L110-L128)
+
+<!-- kb:knowledge owner=feature-huawei-realname-account-check facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**关弹窗与两级实名检测**
+
+复用已有 CDP page（不新建标签页、不导航），先 `dismiss_popups`（最多 3 轮点击引导弹窗关闭按钮，弹窗可能遮挡页面元素）再做检测。`detect_realname_status` 两级策略：主策略读取 `window.myRoleTags`，当它是非空 list 且含 `op_restricted` 或 `op_unverified` 判未认证，非空 list 且不含这两个标签判已认证；备策略检查 `#cf_header_reminder_container` 文案是否含"实名认证"。超时未能判定时兜底返回 False（视为未认证）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/lib/huawei_selectors.py:L558–L605](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/lib/huawei_selectors.py#L558-L605), [jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/check_account.py:L50–L96](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/check_account.py#L50-L96)
+
+<!-- kb:knowledge owner=feature-huawei-realname-account-check facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**设计取舍：稳定性优先的检测策略与时间预算**
+
+Inference / 设计推断（非作者历史意图）：
+
+检测采用两级策略：优先读取 `window.myRoleTags`（代码注释称其不受文案/DOM 布局变化影响），DOM 提醒条 `#cf_header_reminder_container` 作为 JS 变量未就绪时的兜底；超时仍未判定则返回 False（视为未认证），偏向宁可误判未认证也不悬挂。另一取舍：文档字符串声明整个流程 ≤15s 并提供 `--timeout` 参数（默认 15），但在所示实现中 `timeout_s` 形参未被使用，实际耗时由固定的 sleep（2.0s + 关弹窗后 0.5s）和各调用内置超时（connect 15s、detect 8s）累积决定，声明的时间上限在实现中未落实。此为基于所示代码的推断，非作者意图的史料。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/lib/huawei_selectors.py:L561–L605](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/lib/huawei_selectors.py#L561-L605), [jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/check_account.py:L50–L82](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/check_account.py#L50-L82), [jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/check_account.py:L14–L17](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/check_account.py#L14-L17)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-local-doc-ocr-offline.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-local-doc-ocr-offline.md
new file mode 100644
index 00000000..d5fb50eb
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-local-doc-ocr-offline.md
@@ -0,0 +1,46 @@
+---
+title: "local-doc-ocr：本地离线 OCR 管线（RapidOCR：PDF/图片 → Markdown）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/ocr_offline.py:L129-L158, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/write_ocr_md.py:L4-L17, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/setup.py:L41-L55, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/ocr_offline.py:L112-L123, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/ocr_offline.py:L175-L189, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/ocr_offline.py:L231-L234, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/pdf_to_images.py:L100-L108, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/write_ocr_md.py:L46-L47, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/ocr_offline.py:L93-L109, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/ocr_offline.py:L169-L189, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/ocr_offline.py:L22-L32]
+feature: "local-doc-ocr-offline"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/ocr_offline.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/ocr_offline.py", "jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/write_ocr_md.py", "jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/preprocess_img.py", "jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/pdf_to_images.py", "jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/setup.py"]
+---
+
+# local-doc-ocr：本地离线 OCR 管线（RapidOCR：PDF/图片 → Markdown）
+
+<!-- kb:knowledge owner=feature-local-doc-ocr-offline facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**脚本入口与输入输出契约**
+
+`ocr_offline.py` 是主 CLI：`python ocr_offline.py <PDF|图片|图片目录>`，输出 `<同名>_OCR.md`，可选 `--boxes-json` 导出 `_OCR_boxes.json`。辅助入口为 `pdf_to_images.py`（PDF→PNG，支持 `-b` 批量与 `--tiles` 分块）、`preprocess_img.py`（单图预处理）、`write_ocr_md.py`（把 `{source, engine, pages:[{label,text}]}` JSON 汇总为 md，支持 stdin `-`）。ocr_offline.py 通过 `from preprocess_img import preprocess` 复用预处理模块（ocr_offline.py:L32、pdf_to_images.py:L28）；PDF 渲染逻辑在 ocr_offline.py 内部用 fitz 实现（L93–L109），而非调用 pdf_to_images.py。"全本地" 以依赖已装齐为前提：首次运行若缺依赖会联网自动安装（仅白名单），装好后不再联网。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/ocr_offline.py:L129–L158](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/ocr_offline.py#L129-L158), [jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/write_ocr_md.py:L4–L17](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/write_ocr_md.py#L4-L17), [jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/setup.py:L41–L55](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/setup.py#L41-L55)
+
+<!-- kb:knowledge owner=feature-local-doc-ocr-offline facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的行为与边界**
+
+支持 PDF（按页渲染为 PNG）、单张图片及图片目录（按扩展名 png/jpg/jpeg/bmp/tif/tiff/webp 过滤，目录内按名排序）。输出 Markdown 按页/图分节：PDF 分支标题用「第 N 页」（ocr_offline.py:L180），图片分支用去扩展名的文件名（L185–L189）；结尾 stdout 会列出各页的原始 src 路径，供多模态 Agent 对 PDF 中间 PNG 做手写/表格增强（L231–L234）。识别为空的页写入排查建议而非空白（L206–L213）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/ocr_offline.py:L112–L123](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/ocr_offline.py#L112-L123), [jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/ocr_offline.py:L175–L189](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/ocr_offline.py#L175-L189), [jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/ocr_offline.py:L231–L234](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/ocr_offline.py#L231-L234)
+
+<!-- kb:knowledge owner=feature-local-doc-ocr-offline facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证途径**
+
+所示五个脚本均无自动化测试入口；体现的验证手段是运行时自检与防御性输出：`setup.py` 的 `ensure_deps` 用 `importlib.util.find_spec` 逐项检测缺失依赖并打印安装结果（可独立运行，退出码 0/1）；`ocr_offline.py` 对不支持的输入类型、空输入目录以 `sys.exit(1)` 报错退出，`pdf_to_images.py` 对 `-b` 非目录、目录无 PDF、文件不存在同样退出；每页识别为空时在 Markdown 里写入排查建议（提高 DPI、关预处理、走多模态复核等），两个落盘脚本都在输出尾部强制写入人工核对警告。所述脚本之外的测试情况无法从本次提供的证据判断。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/setup.py:L41–L55](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/setup.py#L41-L55), [jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/ocr_offline.py:L112–L123](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/ocr_offline.py#L112-L123), [jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/pdf_to_images.py:L100–L108](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/pdf_to_images.py#L100-L108), [jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/write_ocr_md.py:L46–L47](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/write_ocr_md.py#L46-L47)
+
+<!-- kb:knowledge owner=feature-local-doc-ocr-offline facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**管线结构与控制流**
+
+ocr_offline.py 是主入口：collect_images 把输入分类为 PDF、单图/图片目录，PDF 分支先用 fitz 把各页渲染为 `<文件名>_pages/page_NN.png`，再逐页送 RapidOCR；图片分支直接逐图 OCR。每页结果经 _sort_boxes 做阅读顺序重排（按 y 聚类成行、行内按 x 排序），最后统一拼装为按页分节的 Markdown 落盘。依赖自检委托给同目录 setup.py 的 ensure_deps：它用 importlib.util.find_spec 对照 PACKAGES 白名单逐项检测缺失并自动 pip 安装；ocr_offline.py 只在 try/except 里调用它，若 setup 模块本身不可用则打警告跳过自检继续运行。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/ocr_offline.py:L93–L109](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/ocr_offline.py#L93-L109), [jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/ocr_offline.py:L169–L189](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/ocr_offline.py#L169-L189), [jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/setup.py:L41–L55](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/setup.py#L41-L55), [jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/ocr_offline.py:L22–L32](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/local-doc-ocr/scripts/ocr_offline.py#L22-L32)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-maas-auto-open-models.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-maas-auto-open-models.md
new file mode 100644
index 00000000..1238b791
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-maas-auto-open-models.md
@@ -0,0 +1,46 @@
+---
+title: "华为云 MaaS 预置服务批量开通脚本 auto_open_model.py"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py:L508-L527, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py:L750-L812, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py:L770-L810, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py:L655-L660, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py:L556-L606, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py:L613-L627, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py:L686-L720, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py:L655-L684, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py:L686-L727, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py:L732-L738, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py:L808-L812]
+feature: "maas-auto-open-models"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py"]
+---
+
+# 华为云 MaaS 预置服务批量开通脚本 auto_open_model.py
+
+<!-- kb:knowledge owner=feature-maas-auto-open-models facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**入口与返回契约**
+
+脚本提供两层入口：CLI `main()`（参数 `--cdp-url`、可重复的 `--model`、`--models-file`、`--type-filter`、`--timeout`、`--json`）和核心函数 `auto_open_models(cdp_url, models, type_filter="文本生成", timeout_s=90)`。返回统一结果字典，成功路径经 `make_success("open_models", ...)` 携带 `opened`/`already_opened`/`failed`/`all_done`；连接、导航、表格加载失败分别返回 `make_failure("connect_failed"|"navigate_failed"|"table_timeout", ...)`，进程退出码按 `result["ok"]` 取 0/1。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py:L508–L527](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py#L508-L527), [jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py:L750–L812](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py#L750-L812)
+
+<!-- kb:knowledge owner=feature-maas-auto-open-models facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**命令行参数与默认值**
+
+模型来源优先级：多次指定的 `--model` 参数优先，否则从 `--models-file`（默认 `_DEFAULT_MODELS_FILE`）经 `_load_display_names` 读取，读不到则报 `init` 失败并退出。CDP 地址取 `--cdp-url`，为空时回退 `resolve_cdp_url()` 解析。`--type-filter` 默认 `文本生成`，用于按表格“类型”列过滤；`--timeout` 默认 90 秒（实际用于开通完成等待时被 `min(30, timeout_s)` 截断）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py:L770–L810](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py#L770-L810), [jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py:L655–L660](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py#L655-L660)
+
+<!-- kb:knowledge owner=feature-maas-auto-open-models facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**批量开通与状态回读**
+
+逐模型的"未找到/类型不符/无开通按钮视为已开通"检查只在寻找批量弹窗入口的循环中执行（L556–L582）：一旦某个模型成功打开弹窗即 break；其余 pending 模型不再做这些逐项检查，直接进入弹窗勾选流程（L613–L624），勾选失败仅在 emit 中警告，成功分支事后统一记入 failed。开通完成后脚本重载表格，逐个回读 checked_models 的状态列，含"已开通"才计入 opened，否则或找不到行均记失败。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py:L556–L606](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py#L556-L606), [jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py:L613–L627](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py#L613-L627), [jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py:L686–L720](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py#L686-L720)
+
+<!-- kb:knowledge owner=feature-maas-auto-open-models facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**开通结果的运行时自检**
+
+点击"一键开通"后，完成判定轮询多个信号：订阅按钮从 DOM 消失、弹窗不可见（或查询弹窗可见性抛异常即视为成功）、出现成功提示，任一命中即算 success（L655–L684）；成功后重载表格逐模型回读状态列验证"已开通"（L686–L715）。未勾选模型的失败记录只在成功分支补记（L721–L727），超时分支只把 checked_models 记为"等待开通完成超时"（L732–L738）；CLI 以 result["ok"] 决定退出码 0/1（L808–L812）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py:L655–L684](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py#L655-L684), [jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py:L686–L727](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py#L686-L727), [jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py:L732–L738](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py#L732-L738), [jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py:L808–L812](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/huawei-cloud-maas-setup/scripts/auto_open_model.py#L808-L812)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-opc-add-slide.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-opc-add-slide.md
new file mode 100644
index 00000000..099ff656
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-opc-add-slide.md
@@ -0,0 +1,64 @@
+---
+title: "add_slide.py — 解包 PPTX 幻灯片添加工具"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py:L2-L11, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py:L129-L130, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py:L167-L182, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py:L127-L130, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py:L98-L130, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py:L152-L163, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py:L167-L171, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py:L50-L56, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py:L143-L157, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py:L108-L125, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py:L93-L95, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py:L133-L163, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py:L122-L125]
+feature: "opc-add-slide"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py"]
+---
+
+# add_slide.py — 解包 PPTX 幻灯片添加工具
+
+<!-- kb:knowledge owner=feature-opc-add-slide facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证入口**
+
+所示文件不含测试代码；docstring 中的两条示例命令（复制 slide2、基于 slideLayout2 建空白页）即是最直接的手工验证入口，成功输出为两行摘要（新部件路径与 presentation.xml 注册结果）。未展示仓库内针对此脚本的自动化测试。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py:L2–L11](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py#L2-L11), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py:L129–L130](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py#L129-L130)
+
+<!-- kb:knowledge owner=feature-opc-add-slide facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**入口与契约**
+
+命令行入口为 `add_slide.py <unpacked目录> <source>`，source 可以是 `slideN.xml`（复制现有幻灯片）或 `slideLayoutN.xml`（在该版式上建空白页）。`add_slide(root, source)` 也可作库函数调用，返回两行摘要：新部件路径 `ppt/slides/slideN.xml`，以及在 presentation.xml 中注册的 `<p:sldId id="..." r:id="<rel_id>"/>`——摘要里 sldId 固定显示为 "..."，只有 r:id 是实际生成的关系 id。辅助函数以 `AddSlideError` 报告致命错误，`main()` 将其转为带信息的 `SystemExit`，使函数保持可库用。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py:L167–L182](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py#L167-L182), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py:L127–L130](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py#L127-L130)
+
+<!-- kb:knowledge owner=feature-opc-add-slide facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**四处一致更新**
+
+核心流程 `add_slide()` 先在 `ppt/slides/` 选取下一个空闲编号（`next_free` 扫描 `slideN.xml`），然后按 source 类型生成部件：版式来源写入内置 `EMPTY_SLIDE` 模板并新建指向 `../slideLayouts/<source>` 的 `.rels`；幻灯片来源用 `shutil.copy2` 复制部件，若源 `.rels` 存在则一并复制。随后 `_register_content_type` 向 `[Content_Types].xml` 追加 Override，`_register_in_presentation` 同时改写 presentation.xml.rels 和 presentation.xml。新 `<p:sldId>` 条目插入在 `</p:sldIdLst>` 关闭标签之前（即列表内部末尾）；若列表不存在，则紧跟 `<p:sldMasterIdLst>` 之后新建整个列表。程序输出走 stdout、诊断走 stderr，两个 logger 均 `propagate=False`。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py:L98–L130](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py#L98-L130), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py:L152–L163](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py#L152-L163)
+
+<!-- kb:knowledge owner=feature-opc-add-slide facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**设置面**
+
+无配置文件或环境变量；调用面只有两个位置参数 `unpacked` 和 `source`（argparse 定义）。行为还依赖解包目录中的现有内容：幻灯片编号取自目录中已有的 `slideN.xml`（无则从 1 起），关系 id 取自 presentation.xml.rels 中已有 `Id="rIdN"` 的最大值加一，sldId 取自 presentation.xml 中已有值的最大值加一且下限 256。模块常量固定了幻灯片内容类型、slide 与 slideLayout 两种关系类型，以及空白幻灯片 XML 模板。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py:L167–L171](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py#L167-L171), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py:L50–L56](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py#L50-L56), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py:L143–L157](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py#L143-L157)
+
+<!-- kb:knowledge owner=feature-opc-add-slide facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的行为**
+
+工具支持两种添加方式：以 `slideN.xml` 为源时用 `shutil.copy2` 复制现有幻灯片部件，并在源 `.rels` 存在时一并复制；以 `slideLayoutN.xml` 为源时写入内置的 `EMPTY_SLIDE` 空 spTree 模板，并新建指向 `../slideLayouts/<source>` 的关系文件。版式或幻灯片源文件不存在时抛出 `AddSlideError`，错误信息中携带 root 拼接得到的路径；`main()` 将其转换为带信息的 `SystemExit`。docstring 提示可用 `ls unpacked/ppt/slideLayouts/` 查看可用版式。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py:L2–L11](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py#L2-L11), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py:L108–L125](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py#L108-L125)
+
+<!-- kb:knowledge owner=feature-opc-add-slide facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**实现取舍**
+
+Inference / 设计推断（非作者历史意图）：
+
+注册环节采用纯文本改写而非 XML 解析：`_register_content_type` 和 `_register_in_presentation` 通过字符串 `replace` 在 `</Types>`、`</Relationships>`、`</p:sldIdLst>` 关闭标签前插入条目，`next_rel_id` 也只用正则匹配双引号形式的 `Id="rIdN"`。这是一种推断得出的简化取舍：实现短小、无外部依赖，但对 XML 的排版形式（如属性引号、关闭标签写法）有隐含假设，遇到不匹配的写法时插入会静默失败。另一取舍是复制幻灯片时不重写新部件内部的关系引用，复制 `.rels` 后新部件与源部件指向同一批目标（推断）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py:L93–L95](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py#L93-L95), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py:L133–L163](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py#L133-L163), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py:L122–L125](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/add_slide.py#L122-L125)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-opc-pack-validate.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-opc-pack-validate.md
new file mode 100644
index 00000000..5a79bdd7
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-opc-pack-validate.md
@@ -0,0 +1,62 @@
+---
+title: "OOXML 打包与 schema 校验（opc/pack.py）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/pack.py:L87-L110, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/pack.py:L131-L152, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/pack.py:L94-L110, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/repair.py:L187-L199, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/pack.py:L112-L128, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/pack.py:L87-L92, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/pack.py:L135-L143, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/validate.py:L184-L195, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/repair.py:L112-L141, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/repair.py:L164-L175, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/validate.py:L50-L74, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/validate.py:L167-L195, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/repair.py:L2-L11, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/validate.py:L198-L214, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/validate.py:L120-L155]
+feature: "opc-pack-validate"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/pack.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/pack.py", "jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/repair.py", "jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/unpack.py", "jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/validate.py"]
+---
+
+# OOXML 打包与 schema 校验（opc/pack.py）
+
+<!-- kb:knowledge owner=feature-opc-pack-validate facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**pack 的入口、输入输出与错误契约**
+
+公共入口是 `pack(unpacked, output, do_repair=True, do_validate=True, original=None)`：接受解包目录与输出路径（后缀必须是 .pptx/.docx/.xlsx 之一），按修复→校验→写 ZIP 的顺序执行；校验失败时抛出 `PackError`（RuntimeError 子类），拒绝写出文件，`main()` 再把它转成干净的 SystemExit。命令行用法为 `python3 pack.py unpacked/ out.pptx`，可用 `--no-repair`、`--no-validate`、`--original` 关闭或放宽相应步骤。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/pack.py:L87–L110](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/pack.py#L87-L110), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/pack.py:L131–L152](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/pack.py#L131-L152)
+
+<!-- kb:knowledge owner=feature-opc-pack-validate facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**修复→校验→写包的三段流水线**
+
+pack.py 编排三个模块：repair.repair_all 先对解包目录做生成器怪癖修复并直接写回源 XML（repair.py:L197–L198），随后 validate.validate 做 schema 与结构校验，校验失败抛 PackError 拒绝写出输出文件，最后在临时目录中 condense 并写出 ZIP。三个步骤并非无条件执行：do_repair/do_validate 均可关闭（pack.py:L94、L101）。校验的对象是修复后的源文件，而非仅打包副本。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/pack.py:L94–L110](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/pack.py#L94-L110), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/repair.py:L187–L199](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/repair.py#L187-L199), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/pack.py:L112–L128](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/pack.py#L112-L128)
+
+<!-- kb:knowledge owner=feature-opc-pack-validate facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**配置面：pack() 参数与 CLI 开关**
+
+配置面有两层：库级参数 pack(unpacked, output, do_repair=True, do_validate=True, original=None)（默认全开），以及 CLI 开关 --no-repair、--no-validate、--original 映射到这些参数。--original 提供 baseline 包；validate.py 解压并校验它，仅报告 baseline 中不存在的缺陷（按去掉行号的指纹比对），但 baseline 不可读（BadZipFile/OSError）时退回报告全部错误。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/pack.py:L87–L92](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/pack.py#L87-L92), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/pack.py:L135–L143](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/pack.py#L135-L143), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/validate.py:L184–L195](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/validate.py#L184-L195)
+
+<!-- kb:knowledge owner=feature-opc-pack-validate facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**修复规则与校验范围**
+
+repair_all 对每个 *.xml 依序应用五条规则：子弹百分比、负 extent 翻转（flipH/flipV）、阴影值、重复 shape id、空白保留。注意细节：超出上限的 blurRad/dist/dir 不是被钳制，而是替换为固定回退值（38100/38100/5400000），仅 alpha 值被钳制到 0..100000；空白规则只给不带属性、且首尾含空白的 `t` 元素加 xml:space="preserve"，而非所有含空白的 t。校验按根命名空间选 XSD，未列出的命名空间和 docProps/ 被跳过。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/repair.py:L112–L141](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/repair.py#L112-L141), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/repair.py:L164–L175](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/repair.py#L164-L175), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/validate.py:L50–L74](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/validate.py#L50-L74)
+
+<!-- kb:knowledge owner=feature-opc-pack-validate facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**基线容忍与正则修复的取舍**
+
+baseline 机制是有意的放宽：生成器（如 PptxGenJS 图表子元素顺序）产出的包本身就违反已发布 schema 但能正常打开，拒绝重打包会阻断既有 decks 的每次编辑，因此只报告本次编辑新引入的缺陷；代价是不可读的 baseline 会退回报告全部错误，且指纹（去掉行号的 part+message）可能把不同位置的同类缺陷视为相同。修复层用逐条正则规则针对 PptxGenJS 的具体观察失败，收益是精准、可计数，限制是仅覆盖已枚举的怪癖，其他生成器的问题落在 validate 层兜底。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/validate.py:L167–L195](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/validate.py#L167-L195), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/repair.py:L2–L11](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/repair.py#L2-L11)
+
+<!-- kb:knowledge owner=feature-opc-pack-validate facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**校验入口与所覆盖的检查**
+
+validate.py 可独立运行（`python3 validate.py unpacked/ [--baseline ...]`）：失败时经 stderr 列出前 40 条错误并以退出码 1 结束，全部通过则 stdout 输出 "All validations PASSED!"。它做两层检查：逐 part 的 XSD 校验（含不可编译 schema 的跳过与命名空间映射例外），以及跨 part 结构检查——slide 的 .rels 存在、r:id/r:embed 引用存在、恰好一条 slideLayout 关系、每张 slide 内 shape id 唯一。所示输入中未包含这些模块的测试用例。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/validate.py:L198–L214](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/validate.py#L198-L214), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/validate.py:L120–L155](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/validate.py#L120-L155)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-plugin-package-initializer.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-plugin-package-initializer.md
new file mode 100644
index 00000000..57ca35d5
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-plugin-package-initializer.md
@@ -0,0 +1,56 @@
+---
+title: "plugin-creator 插件包脚手架初始化（init_plugin.py）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py:L91-L103, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py:L186-L191, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py:L141-L162, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py:L1-L18, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py:L184-L202, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py:L91-L107, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py:L129-L147, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py:L150-L165, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py:L150-L162, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py:L196-L202]
+feature: "plugin-package-initializer"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py"]
+---
+
+# plugin-creator 插件包脚手架初始化（init_plugin.py）
+
+<!-- kb:knowledge owner=feature-plugin-package-initializer facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**环境变量与输出位置**
+
+唯一配置项是环境变量 `JIUWENSWARM_DATA_DIR`：设置时数据根为该路径（支持 `~` 展开），未设置或为空白时默认 `~/.jiuwenswarm`。默认输出目录为 `<data-dir>/agent/workspace/plugins/plugin_packages/local/<plugin-name>/`，用法文本中亦有说明。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py:L91–L103](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py#L91-L103), [jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py:L186–L191](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py#L186-L191)
+
+<!-- kb:knowledge owner=feature-plugin-package-initializer facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证入口**
+
+Inference / 设计推断（非作者历史意图）：
+
+本片段未附带任何测试或文档证据，无法指出针对该脚本的既有测试入口；其行为只能由源码本身（如 158-162 行的存在性检查、141-145 行的名称校验）佐证。仓库其余部分的测试未在本次输入中展示。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py:L141–L162](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py#L141-L162)
+
+<!-- kb:knowledge owner=feature-plugin-package-initializer facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**命令行入口与错误契约**
+
+CLI 入口为 `init_plugin.py <plugin-name>` 或 `init_plugin.py <path-to-package-dir>`（见文件头用法说明）。无参数时打印用法到 fd 1 并返回退出码 1。main() 仅捕获 `ValueError`（来自名称校验、路径约束与目录已存在检查），把异常文本写入 fd 1 并返回 1；目录创建与文件写入（init_package 内）抛出的 OSError 不在该捕获范围内，会产生未捕获的回溯。正常路径返回 0，并经 `os.write(1, ...)` 输出进度信息（docstring 注明是为规避 G.LOG.02 而避免 print/sys.stdout）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py:L1–L18](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py#L1-L18), [jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py:L184–L202](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py#L184-L202)
+
+<!-- kb:knowledge owner=feature-plugin-package-initializer facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**单文件 CLI 脚手架：解析目标目录并生成骨架**
+
+本组件是一个自包含的 Python CLI 脚本，控制流为 main() → resolve_init_target()（把名称或显式路径解析为包目录）→ init_package()（创建目录并写入两个模板文件）。目录解析基于环境变量 JIUWENSWARM_DATA_DIR（默认 ~/.jiuwenswarm），包落在 <data-dir>/agent/workspace/plugins/plugin_packages/local/ 下。init_package 对任何输入（含显式路径）统一执行 basename 的长度与 kebab-case（NAME_RE）校验，再做目标目录存在性检查（拒绝覆盖）。名称输入分支额外先经 _assert_package_id_available 检查 local 与 built_in 目录冲突；显式路径分支只要求父目录是 local plugin_packages，提前返回，不经 built_in 冲突检查。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py:L91–L107](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py#L91-L107), [jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py:L129–L147](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py#L129-L147), [jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py:L150–L165](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py#L150-L165)
+
+<!-- kb:knowledge owner=feature-plugin-package-initializer facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**永不覆盖与轻量校验的取舍**
+
+脚本采取"永不覆盖"策略：目标目录已存在即抛 ValueError，提示重命名或删除旧包（local 冲突）或换名（built_in 冲突）。校验强度按输入类型不同：名称输入受 kebab-case 正则、长度下限以及 local/built_in 双重冲突检查约束；显式路径输入绕过 built_in 冲突检查，但仍受父目录必须是 local plugin_packages 的约束，并统一受 init_package 内的 basename kebab-case/长度校验和目录存在性检查约束。main() 只捕获 ValueError（返回退出码 1），目录/文件写操作可能抛出的 OSError 不在捕获范围。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py:L129–L147](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py#L129-L147), [jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py:L150–L162](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py#L150-L162), [jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py:L196–L202](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/init_plugin.py#L196-L202)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-plugin-package-layered-validator.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-plugin-package-layered-validator.md
new file mode 100644
index 00000000..b16e548b
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-plugin-package-layered-validator.md
@@ -0,0 +1,56 @@
+---
+title: "plugin-creator 插件包分层校验器（validate_plugin.py L0/L1/L2）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py:L1-L15, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py:L955-L968, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin_hot_load_worker.py:L136-L217, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py:L157-L170, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py:L34-L44, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin_hot_load_worker.py:L100-L133, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin_hot_load_worker.py:L288-L306, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py:L823-L891, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py:L230-L246, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py:L258-L266, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py:L522-L543, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py:L648-L652, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py:L806-L891, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py:L513-L543, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py:L782-L798]
+feature: "plugin-package-layered-validator"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py", "jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin_hot_load_worker.py"]
+---
+
+# plugin-creator 插件包分层校验器（validate_plugin.py L0/L1/L2）
+
+<!-- kb:knowledge owner=feature-plugin-package-layered-validator facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**三层结构与进程边界**
+
+校验分三层：L0 规范与质量（占位符残留、展示字段），L1 静态校验（加载阻塞项，纯 stdlib：json/ast/文件系统），L2 热加载由子进程运行 worker、主脚本只解析结果；L0/L1 都通过才执行 L2（validate_plugin.py:2-8, 955-963）。L1 对 manifest 声明的 tools/rails 类做 AST 级检查（继承基类、无参构造、ToolCard 字面量、运行时路径策略），路径解析规则对齐加载器 `_resolve_new_manifest_path`（validate_plugin.py:197-222, 722-745, 448-491）。进程隔离的动机是让 openjiuwen 的运行时副作用（Runner.resource_mgr、DeepAgent）完全留在 worker 子进程内，主脚本不 import openjiuwen（worker:2-5, validate_plugin.py:801-803）；worker 内部再分三段：搭最简 agent（失败算环境问题 skip）、真实 load_plugin（失败算包问题 fail）、对绑定的 Tool/Rail 做冒烟并卸载（worker:163-306）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py:L1–L15](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py#L1-L15), [jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py:L955–L968](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py#L955-L968), [jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin_hot_load_worker.py:L136–L217](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin_hot_load_worker.py#L136-L217)
+
+<!-- kb:knowledge owner=feature-plugin-package-layered-validator facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**配置项与环境变量**
+
+唯一的运行时配置是环境变量 `JIUWENSWARM_DATA_DIR`：非默认实例由宿主注入，缺省回退到 `~/.jiuwenswarm`；它决定插件包的查找目录 `<data>/agent/workspace/plugins/plugin_packages/local`（validate_plugin.py:157-170）。其余行为由模块内常量固定：热加载 worker 超时 120 秒（HOT_LOAD_TIMEOUT_SEC），worker 路径取脚本同目录（validate_plugin.py:34-35）；TODO 扫描仅覆盖 .md/.py/.json 后缀并跳过 `__pycache__`/`.git`/`.state` 目录（validate_plugin.py:42-44）。CLI 层面用户只能通过 `--no-hot-load` 改变执行范围（validate_plugin.py:941-943）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py:L157–L170](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py#L157-L170), [jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py:L34–L44](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py#L34-L44)
+
+<!-- kb:knowledge owner=feature-plugin-package-layered-validator facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**测试与自校验入口**
+
+在所提供的源码切片中没有针对这两个脚本的测试文件；可观察到的验证入口是脚本自身的自校验路径：L2 冒烟本身会用良性输入逐个调用 Tool.invoke 和每个 Rail callback（含对 exception 事件注入 RuntimeError），并核对卸载数量，等于把运行时契约作为可执行断言（worker:57-133, 229-301）。主脚本对 worker 输出协议做了防御性处理：未知 status、无 JSON、超时均转为 SKIP 而非崩溃（validate_plugin.py:806-891）。此为部分输入的观察；不能据此断言仓库中不存在其他测试。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin_hot_load_worker.py:L100–L133](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin_hot_load_worker.py#L100-L133), [jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin_hot_load_worker.py:L288–L306](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin_hot_load_worker.py#L288-L306), [jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py:L823–L891](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py#L823-L891)
+
+<!-- kb:knowledge owner=feature-plugin-package-layered-validator facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**三层校验的实际覆盖范围**
+
+L0 质量层扫描包内残留的 `[TODO` 占位符，但仅限 .md/.py/.json 后缀、跳过 `__pycache__`/`.git`/`.state` 目录且忽略读不了的文件；并校验 manifest 的 i18n 展示字段、tags/quick_inputs 恰好 3 项、`default_init_input` 与 `quick_inputs[0]` 的 en/zh 值一致、README.md 存在等。L1 静态层检查 manifest 基本项（package_type=plugin、source=local、id 等于目录名等）、skills 目录的 SKILL.md frontmatter，以及对 tools/rails 声明类做 AST 检查（继承基类、无参构造、async invoke、ToolCard 字面量的 id/name/input_params）；找不到 ToolCard 字面量或 input_params 不是字面量 dict 时只降级为 warning，且 `mcps` 仅在取值为真时才报错。L2 在子进程中经真实 `load_plugin` 链加载并对绑定的 Tool.invoke 和每个 Rail callback 做冒烟，最后核对卸载数量。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py:L230–L246](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py#L230-L246), [jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py:L258–L266](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py#L258-L266), [jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py:L522–L543](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py#L522-L543), [jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py:L648–L652](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py#L648-L652)
+
+<!-- kb:knowledge owner=feature-plugin-package-layered-validator facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**进程隔离与静态近似带来的取舍**
+
+Inference / 设计推断（非作者历史意图）：
+
+成本侧：L2 依赖 openjiuwen 运行环境，环境问题（ImportError、agent 搭建失败、worker 崩溃/超时/无 JSON）会以有效 skip payload 或主脚本的防御分支转化为 SKIP，退出码仍为 1（PARTIAL），用户需要区分“包坏”与“环境不可用”。收益侧：主脚本完全不 import openjiuwen，运行时副作用隔离在子进程 worker 内，且 worker 用真实 load_plugin/unload_extension 链和 Tool.invoke、Rail callback 冒烟验证运行时契约。L1 选择 AST 近似而非导入执行：找不到字面量 ToolCard(...) 或 input_params 非字面量 dict 时只降级为 warning、放弃该项检查，换取纯 stdlib、无副作用且全量报错的安全性。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py:L806–L891](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py#L806-L891), [jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin_hot_load_worker.py:L136–L217](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin_hot_load_worker.py#L136-L217), [jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py:L513–L543](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py#L513-L543), [jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py:L782–L798](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/validate_plugin.py#L782-L798)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-ppt-deck-finalize.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-ppt-deck-finalize.md
new file mode 100644
index 00000000..30a5b78e
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-ppt-deck-finalize.md
@@ -0,0 +1,46 @@
+---
+title: "一键成片流水线与质量门禁（finalize_deck.py）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/finalize_deck.py:L100-L115, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/finalize_deck.py:L192-L197, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/finalize_deck.py:L104-L115, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/finalize_deck.py:L123-L130, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/merge_slides.py:L439-L449, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/merge_slides.py:L85-L122, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/merge_slides.py:L168-L212, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/fill_cover.py:L145-L181, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/make_blank_template.py:L11-L29, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/finalize_deck.py:L132-L163, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/finalize_deck.py:L60-L66, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/finalize_deck.py:L165-L188]
+feature: "ppt-deck-finalize"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/finalize_deck.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/finalize_deck.py", "jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/make_blank_template.py", "jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/fill_cover.py", "jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/prune.py", "jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/merge_slides.py"]
+---
+
+# 一键成片流水线与质量门禁（finalize_deck.py）
+
+<!-- kb:knowledge owner=feature-ppt-deck-finalize facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**命令行入口与输出契约**
+
+`finalize_deck.py content.pptx out.pptx` 是公开入口：接收生成的 PptxGenJS 内容 PPTX 与输出路径，可选 `--template`、`--order`、`--cover-title`、`--cover-meta`、`--keep-workdir` 等参数。程序输出走 stdout、诊断走 stderr，两条流都经 logging 以纯 `%(message)s` 格式输出，便于下游解析。致命错误由 `FinalizeError` 表达，仅在 `main()` 入口转为带错误信息的 `SystemExit`，保持辅助函数可作库使用；成功时最终打印 `finalize_deck: OK`。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/finalize_deck.py:L100–L115](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/finalize_deck.py#L100-L115), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/finalize_deck.py:L192–L197](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/finalize_deck.py#L192-L197)
+
+<!-- kb:knowledge owner=feature-ppt-deck-finalize facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**实际参数与默认值**
+
+主要设置：`--template` 默认 `references/template.pptx`（相对技能根）；`--order` 默认 `"t1,s*,t5"`（模板封面 + 全部内容页 + 模板结尾），`s*` 在运行时展开为 s1..sN；`--template-layout` 默认 `slideLayout7.xml`（注意 merge_slides.py 自身的同名默认是 `slideLayout6.xml`，仅当通过 finalize_deck 调用时才是 7）；`--source-layout-mode` 取 `template`/`source`，默认 `template`。另有一致性约束：任务产物（content 与 out）不得位于技能目录内，否则直接报错。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/finalize_deck.py:L104–L115](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/finalize_deck.py#L104-L115), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/finalize_deck.py:L123–L130](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/finalize_deck.py#L123-L130), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/merge_slides.py:L439–L449](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/merge_slides.py#L439-L449)
+
+<!-- kb:knowledge owner=feature-ppt-deck-finalize facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持行为与协作组件**
+
+端到端支持：模板封面/结尾混排、跨画布坐标缩放（`scale_slide_xml` 调整 off/ext/chOff/字号/线宽）、图表与内嵌工作簿改名复制（规避 pptxgenjs 与模板同号 chart1.xml 冲突）、pptxgenjs 图表 XML 的 schema 修正（dPt/dLbls 顺序、悬空 axId）。封面填充由 `fill_cover.py` 完成：替换 ctrTitle 段落 runs、向 idx=1 占位符的 部门/汇报人/日期 标签后追加值。模板由 `make_blank_template.py` 生成，t1–t5 五页结构（封面/目录/两张空白/结尾），封面标题刻意留空并带 `<a:pPr>`，供 fill_cover 写入。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/merge_slides.py:L85–L122](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/merge_slides.py#L85-L122), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/merge_slides.py:L168–L212](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/merge_slides.py#L168-L212), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/fill_cover.py:L145–L181](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/fill_cover.py#L145-L181), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/make_blank_template.py:L11–L29](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/make_blank_template.py#L11-L29)
+
+<!-- kb:knowledge owner=feature-ppt-deck-finalize facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**Orchestrated pipeline over unpacked OOXML intermediates**
+
+finalize_deck.py is a process-level orchestrator: it unpacks the template and the generated content PPTX into a throwaway temp dir via subprocess calls to opc/unpack.py, expands the --order tokens (s* becomes s1..sN based on counted source slides), then runs merge_slides.py, optionally fill_cover.py, opc/prune.py and opc/pack.py, repacking into the final PPTX. Each child step runs via run(), which re-raises any non-zero exit as FinalizeError pointing at --keep-workdir for debugging; workdir is removed in a finally block unless kept. After packing, control returns to finalize_deck itself for post-hoc quality gates computed by reading the output zip (digest, cover_title_filled).
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/finalize_deck.py:L132–L163](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/finalize_deck.py#L132-L163), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/finalize_deck.py:L60–L66](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/finalize_deck.py#L60-L66), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/finalize_deck.py:L165–L188](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/finalize_deck.py#L165-L188)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-ppt-evidence-preparation.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-ppt-evidence-preparation.md
new file mode 100644
index 00000000..c86393c3
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-ppt-evidence-preparation.md
@@ -0,0 +1,64 @@
+---
+title: "prepare_evidence.py — Evidence Plan Preparation and Review Lifecycle"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L309-L316, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L95-L102, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L52-L53, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L322-L345, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L231-L253, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L148-L154, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L346-L348, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L95-L125, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L99-L101, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L216-L226, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L4-L7, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L294-L316, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L346-L356, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L358-L360, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L322-L349, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L68-L76]
+feature: "ppt-evidence-preparation"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py"]
+---
+
+# prepare_evidence.py — Evidence Plan Preparation and Review Lifecycle
+
+<!-- kb:knowledge owner=feature-ppt-evidence-preparation facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**Plan fields and CLI flags with their defaults**
+
+The plan supplies `asset_root` and `analysis_root`, defaulting to `<project>/assets` and `<project>/analysis`; both must resolve inside the project root or the run exits 1 (L309–L316). Per-item paper selectors default `min_confidence` to 0.55 and `include_caption` to false, which picks `image_path` over `image_with_caption_path` (L95–L102, L156–L157). Retry semantics are constrained: `--force` or an explicit `--item` triggers preparation only when the item's status is one of `planned`/`acquiring`/`needs-manual` (PREPARABLE_STATUSES) and only in a non-review pass; a bare run without selection prepares only `planned` items (L52–L53, L322–L345).
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L309–L316](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py#L309-L316), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L95–L102](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py#L95-L102), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L52–L53](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py#L52-L53), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L322–L345](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py#L322-L345)
+
+<!-- kb:knowledge owner=feature-ppt-evidence-preparation facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**Status/review lifecycle across route families**
+
+For file-bearing routes the lifecycle is gated: `--approve` requires the destination file to exist and sets status `ready` with review `approved`; `--used` additionally requires review status `approved` and marks status `used` (L236–L253). Native routes (`native-chart`, `native-drawing`) bypass these file and approval checks on both actions — they go straight to `ready`/`used` with review `not-required` (L231–L247). Failed or ambiguous preparation lands in `needs-manual` with review `pending`, e.g. ambiguous paper selection (L148–L154) or any per-item exception (L346–L348).
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L231–L253](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py#L231-L253), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L148–L154](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py#L148-L154), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L346–L348](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py#L346-L348)
+
+<!-- kb:knowledge owner=feature-ppt-evidence-preparation facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**Automatic selection versus human visual gates**
+
+Inference / 设计推断（非作者历史意图）：
+
+Paper-figure selection scores candidates by confidence (default floor 0.55), +2 for an exact normalized label match and +0.5 per caption-keyword hit; automatic selection succeeds only when there is a selector (label or keywords) or exactly one candidate, and either a sole ranked candidate or a top score exceeding the runner-up by more than 0.15 — otherwise the item is marked `needs-manual` for human review against the contact sheet (L95–L125, L148–L154). AI illustrations are deliberately kept manual: the script only writes a prompt file and warns that AI cannot serve as factual evidence (L216–L226, and the module docstring L4–L7). The confidence floor is a narrowing filter only; the code comment states approval remains the hard visual gate (L99–L101). These intent statements are design rationale from the source comments, not independent documentation.
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L95–L125](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py#L95-L125), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L99–L101](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py#L99-L101), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L216–L226](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py#L216-L226), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L4–L7](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py#L4-L7)
+
+<!-- kb:knowledge owner=feature-ppt-evidence-preparation facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**CLI surface and exit behavior**
+
+`main()` accepts a positional `project` plus `--plan` (default `evidence-plan.json`), repeatable `--item`/`--approve`/`--used`/`--reject`, and `--force` (L294–L302). It returns 1 with a logged error when the plan file is missing (L305–L307) or when `asset_root`/`analysis_root` resolve outside the project root (L311–L316); per-item preparation failures do not set the exit code — the run still ends with `return 0`, reporting them as warnings in the completion line (L346–L353). Uncaught exceptions elsewhere (e.g. JSON parsing at L308, `save_plan` at L350) propagate and terminate via `raise SystemExit(main())` with a nonzero status.
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L294–L316](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py#L294-L316), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L346–L356](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py#L346-L356), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L358–L360](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py#L358-L360)
+
+<!-- kb:knowledge owner=feature-ppt-evidence-preparation facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**Selective dispatch and review pass structure**
+
+Per item, `main()` first enforces path containment for path-bearing routes (L328–L331), then branches: if `--approve`/`--used`/`--reject` names were given (a review pass), it calls `use_item`, `approve_item`, or writes a `rejected` review without invoking any route handler (L332–L338, L322–L323). Route dispatch through `prepare_item` happens only in a non-review pass, and only for in-scope items whose status is in `PREPARABLE_STATUSES` (`planned`/`acquiring`/`needs-manual`) and that are `planned`, explicitly re-selected, or forced (L339–L345). Any exception inside this loop downgrades the item to `needs-manual` with a `pending` review rather than aborting the run (L346–L349).
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L322–L349](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py#L322-L349), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L52–L53](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py#L52-L53)
+
+<!-- kb:knowledge owner=feature-ppt-evidence-preparation facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**Runtime gates on review actions and asset copies**
+
+Review actions validate state at runtime: `approve_item` raises `FileNotFoundError` if the destination asset is missing, and `use_item` additionally requires `review.status == "approved"` before setting status `used`; both native routes (`native-chart`, `native-drawing`) bypass these checks (L231–L253). For copies, `copy_asset` raises when the source is missing, and when the destination exists with different content it raises `FileExistsError` unless `--force`; with identical content it returns early, but with `force` set it still performs `shutil.copy2` (L68–L76). No test entry points for this script appear in the shown inputs.
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L231–L253](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py#L231-L253), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py:L68–L76](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/prepare_evidence.py#L68-L76)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-ppt-execution-lock-validator.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-ppt-execution-lock-validator.md
new file mode 100644
index 00000000..ec5a18a0
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-ppt-execution-lock-validator.md
@@ -0,0 +1,46 @@
+---
+title: "PPT 执行锁（execution-lock.json）语义校验器"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-evidence-plan.js:L106-L133, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-execution-lock.js:L16-L19, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-execution-lock.js:L21-L23, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-execution-lock.js:L182-L199, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-evidence-plan.js:L26-L36, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-evidence-plan.js:L115-L124, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-execution-lock.js:L129-L179, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-execution-lock.js:L235-L246, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-execution-lock.js:L11-L19, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-execution-lock.js:L56-L76, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-execution-lock.js:L98-L101, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-evidence-plan.js:L96-L101]
+feature: "ppt-execution-lock-validator"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-execution-lock.js"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-execution-lock.js", "jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-evidence-plan.js"]
+---
+
+# PPT 执行锁（execution-lock.json）语义校验器
+
+<!-- kb:knowledge owner=feature-ppt-execution-lock-validator facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证入口**
+
+在所提供的源码范围内，两个脚本本身就是验证工具（各自可直接作为 CLI 运行并对非法输入返回非零退出码），但没有看到针对这两个校验器自身的单元测试文件。validate-evidence-plan.js 通过 `require.main === module` 守卫同时支持 CLI 与被 require 两种用法（第 132-133 行），这是使其可被测试复用的结构；但所示证据不含任何测试调用，无法断言测试存在与否。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-evidence-plan.js:L106–L133](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-evidence-plan.js#L106-L133), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-execution-lock.js:L16–L19](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-execution-lock.js#L16-L19)
+
+<!-- kb:knowledge owner=feature-ppt-execution-lock-validator facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**分层校验与委托边界**
+
+执行锁校验器是编排层：projectRoot 取 lock 文件所在目录，skillRoot 取脚本上级目录；先做参数/位置检查、解析，再校验 template、brand 常量、deck 级策略、逐页契约，最后校验资产与证据引用。version 2 时把证据校验委托给 validateEvidencePlan（传入 phase 与 pageIds），并把子级 errors/warnings 合并进自身输出；version 1 走 legacy 内联 assets 列表并给出迁移告警。注意：资产路径解析基准不同——内联 assets 相对 lock 所在目录，而 validateEvidencePlan 内部把 projectRoot 定义为 evidence-plan 文件所在目录（validate-evidence-plan.js L27–L28、L41–L42），不一定是 lock 目录；且 skill 目录禁入检查位于两个脚本的 CLI main 中，被 require 调用 validateEvidencePlan 时不执行。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-execution-lock.js:L21–L23](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-execution-lock.js#L21-L23), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-execution-lock.js:L182–L199](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-execution-lock.js#L182-L199), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-evidence-plan.js:L26–L36](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-evidence-plan.js#L26-L36), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-evidence-plan.js:L115–L124](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-evidence-plan.js#L115-L124)
+
+<!-- kb:knowledge owner=feature-ppt-execution-lock-validator facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**逐页契约与证据引用校验**
+
+每页校验 id 形如 `P\d{2,3}` 且唯一、role/rhythm/component_policy/core_message/composition 合法，visual_strategy 的 primary 与 fallback 均须属于策略集且 fallback 不能是 hybrid；fixed-cover/fixed-closing 页 primary 必须 template，standard-content 页 primary 不能 template、必须有 summary，dense/anchor 节奏的 standard-content 页还须 reference_ids（或 reference_waiver）及非 none 的 evidence_visual.kind。页引用的 evidence asset_id 必须已知；仅当 version 2 走 evidence-plan 时才进一步校验该项归属本页（L239），legacy 内联资产只检查 id 存在（L237）。version 2 要求非空 evidence_plan 路径并把 phase 与 pageIds 传给 validateEvidencePlan 合并其错误；version 1 走内联 assets 校验并警告迁移。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-execution-lock.js:L129–L179](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-execution-lock.js#L129-L179), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-execution-lock.js:L182–L199](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-execution-lock.js#L182-L199), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-execution-lock.js:L235–L246](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-execution-lock.js#L235-L246)
+
+<!-- kb:knowledge owner=feature-ppt-execution-lock-validator facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**--phase 校验器选项与锁文件中的受检常量**
+
+--phase 是校验器 CLI 的进程参数（从 process.argv 读取），不是锁文件字段；合法值仅 design/generate/deliver，缺省为 design，非法值打印 usage 并退出 2。phase 决定资产就绪门槛：design 阶段不检查就绪状态；generate 及之后 required 资产不得处于 planned/acquiring/needs-manual（evidence-plan 侧要求 ready/used）；deliver 阶段 required 资产必须已是 used。锁文件本身的可配置项被严格收窄：version 只允许 1 或 2；template.content_shell 必须为 blank-content；canvas_mode 只允许 template-master 或 10x5.625-compatible，且 template-master 模式下 authoring_canvas/merge_mode/content_layout/footer_mode 均为固定值；brand 颜色、字体、footer/summary_banner 等十二个品牌常量逐一硬编码比对（注释说明需与 base/execution-lock-reference.json 和 components.js 的 THEME 三处同步修改）。typography_policy 设最低字号：title ≥20pt、body ≥9pt、absolute ≥7pt。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-execution-lock.js:L11–L19](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-execution-lock.js#L11-L19), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-execution-lock.js:L56–L76](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-execution-lock.js#L56-L76), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-execution-lock.js:L98–L101](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-execution-lock.js#L98-L101), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-evidence-plan.js:L96–L101](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/validate-evidence-plan.js#L96-L101)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-ppt-figure-panel-layout.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-ppt-figure-panel-layout.md
new file mode 100644
index 00000000..dd928c07
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-ppt-figure-panel-layout.md
@@ -0,0 +1,46 @@
+---
+title: "PPT 图表面板布局引擎（figure-panel.js）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/figure-panel.js:L82-L104, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/figure-panel.js:L34-L37, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/figure-panel.js:L1-L8, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/figure-panel.js:L82-L92, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/figure-panel.js:L10-L21, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/figure-panel.js:L93-L98, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/figure-panel.js:L23-L41]
+feature: "ppt-figure-panel-layout"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/figure-panel.js"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/figure-panel.js"]
+---
+
+# PPT 图表面板布局引擎（figure-panel.js）
+
+<!-- kb:knowledge owner=feature-ppt-figure-panel-layout facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**公开接口**
+
+模块导出 `pngSize(filePath)`、`layoutFigures(figs, w, h)`、`renderFigurePanel({ slide, figures, bounds })` 以及常量 `WIDE_AR`、`LABEL_H`、`GAP`（第 104 行）。核心入口 `renderFigurePanel` 接收 pptxgenjs 的 slide、figures 数组（含 path 与可选 label）和 bounds 区域，返回 `{ rects, rows, scale, totalH }`。`pngSize` 对非 PNG 或缺少 IHDR 的文件抛出带路径的 Error（第 34-35 行）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/figure-panel.js:L82–L104](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/figure-panel.js#L82-L104), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/figure-panel.js:L34–L37](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/figure-panel.js#L34-L37)
+
+<!-- kb:knowledge owner=feature-ppt-figure-panel-layout facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**职责与数据流**
+
+文件刻意保持纯几何引擎 + 渲染函数的结构，与 system-diagram.js 的拆分方式对应：components.js 只保留薄封装 addFigurePanel（第 2-4 行注释，属文档声明）。数据流：renderFigurePanel 先用 pngSize 同步读取 PNG IHDR 头得到宽高并算出宽高比（第 83-86 行），再由 layoutFigures 在 w×h 区域内计算行分组与矩形坐标，最后逐个 addImage/addText 写入 slide。同步是硬约束：slides.js 顺序调用组件，无法使用异步的 sharp（第 6-7 行注释）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/figure-panel.js:L1–L8](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/figure-panel.js#L1-L8), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/figure-panel.js:L82–L92](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/figure-panel.js#L82-L92)
+
+<!-- kb:knowledge owner=feature-ppt-figure-panel-layout facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**布局常量与标签样式设置**
+
+布局由三个模块内常量控制：`WIDE_AR = 2.5`（宽高比达到该值的图独占一行）、`LABEL_H = 0.22` 英寸（每行下方中文标签保留高度）、`GAP = 0.12` 英寸（行间及并排图之间距）。L11–L12 注释要求 WIDE_AR 必须介于 1.48（Alita GAIA 表格）与 2.96（Alita 架构图）之间，是依据真实论文校准的区间。标签字体 `Microsoft YaHei` 与颜色 `595757` 从 components.js 镜像复制（仅这两项，注释 L17–L21 说明是为避免循环依赖）；渲染时字号固定 10、居中、fit 为 shrink（L94–L98）。常量随模块一并导出（L104）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/figure-panel.js:L10–L21](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/figure-panel.js#L10-L21), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/figure-panel.js:L93–L98](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/figure-panel.js#L93-L98)
+
+<!-- kb:knowledge owner=feature-ppt-figure-panel-layout facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**同步几何与手工 PNG 解析的代价**
+
+L6–L7 注释明确说明：slides.js 顺序调用组件，因此本文件刻意全部同步，无法使用异步的 sharp 读图。由此 `pngSize` 只能用同步 fs 手工解析 PNG IHDR 头（读取前 24 字节，L26–L36），这把输入限制为 PNG 一种格式，非 PNG 或缺 IHDR 直接抛错。另一取舍是标签与间距保持绝对尺寸、仅图片缩放（L39–L41），保证排版再紧标签也可读，代价是极小区域中图片占比被进一步压缩。`LABEL_FONT`/`LABEL_COLOR` 复制而非导入，注释归因于 components.js 反向依赖本模块会形成循环（L17–L19）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/figure-panel.js:L1–L8](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/figure-panel.js#L1-L8), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/figure-panel.js:L23–L41](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/figure-panel.js#L23-L41)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-ppt-opc-thumbnail.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-ppt-opc-thumbnail.md
new file mode 100644
index 00000000..8cd7c961
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-ppt-opc-thumbnail.md
@@ -0,0 +1,64 @@
+---
+title: "Deck Thumbnail Contact-Sheet Renderer (thumbnail.py)"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py:L66-L86, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py:L89-L103, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py:L52-L55, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py:L107-L111, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py:L126-L128, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py:L106-L116, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py:L135-L140, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py:L68-L70, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py:L121-L128, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py:L114-L116, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py:L58-L63, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py:L121-L121, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py:L7-L8, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py:L4-L5]
+feature: "ppt-opc-thumbnail"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py"]
+---
+
+# Deck Thumbnail Contact-Sheet Renderer (thumbnail.py)
+
+<!-- kb:knowledge owner=feature-ppt-opc-thumbnail facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**渲染流水线与数据流**
+
+流程为两阶段转换:`_run()` 在临时目录中调用 `render_pages()`,先用 LibreOffice `soffice --headless --convert-to pdf` 把 deck 转成 PDF(check=True, 300s 超时),再用 PyMuPDF(fitz)按 `CELL_W/page宽` 的缩放把每页栅格化为 PIL RGB 图像;随后 `build_sheet()` 把图像按行列贴到白色画布并标注 `slideN.xml` 标签。`find_soffice()` 依次探测 PATH 中的 `soffice` 和 macOS 应用路径,找不到即抛 `ThumbnailError`。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py:L66–L86](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py#L66-L86), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py:L89–L103](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py#L89-L103)
+
+<!-- kb:knowledge owner=feature-ppt-opc-thumbnail facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**配置项与常量默认值**
+
+用户可配置项仅有 CLI 的 `prefix`(默认 `thumbnails`)和 `--cols`(默认 3)。布局常量硬编码:`CELL_W=480` 像素/缩略图、`LABEL_H=22`、`PAD=8`、`MAX_PER_SHEET=24`(超过则拆成 `prefix-1.jpg`、`prefix-2.jpg`…);JPEG 保存质量固定 88。无环境变量或配置文件。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py:L52–L55](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py#L52-L55), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py:L107–L111](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py#L107-L111), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py:L126–L128](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py#L126-L128)
+
+<!-- kb:knowledge owner=feature-ppt-opc-thumbnail facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**API 与错误契约**
+
+入口为 CLI：位置参数 `deck`（输入 .pptx）、可选 `prefix`（默认 `thumbnails`）与 `--cols`（默认 3）。程序输出经 `thumbnail.out` logger 走 stdout，诊断走 stderr，格式均为裸 `%(message)s`。错误契约需区分：`main()` 仅把 `ThumbnailError` 转为带消息的 `SystemExit`（L139–L140）；而 L68–L70 的 `subprocess.run(check=True, timeout=300)` 失败或超时会直接抛出 `subprocess.CalledProcessError`/`TimeoutExpired`，不会经过该转换。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py:L106–L116](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py#L106-L116), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py:L135–L140](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py#L135-L140), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py:L68–L70](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py#L68-L70)
+
+<!-- kb:knowledge owner=feature-ppt-opc-thumbnail facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的渲染行为**
+
+把 deck 经 LibreOffice 无头转 PDF，再用 PyMuPDF 按宽度缩放到 480px 栅格化每页，贴成带标签的白色网格并以 JPEG（quality=88）落盘；超过 24 页拆分为 `prefix-1.jpg`、`prefix-2.jpg`…。注意：单元格标签是按 PDF 页序生成的 `slide{i+1}.xml`（L121），并不读取 deck 内实际的 OPC 部件名，因此页序与部件名的对应是假定而非查证。缺失输入文件、找不到 LibreOffice、无 PDF 产出或缺 PyMuPDF 时给出显式错误消息。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py:L66–L86](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py#L66-L86), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py:L121–L128](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py#L121-L128), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py:L114–L116](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py#L114-L116)
+
+<!-- kb:knowledge owner=feature-ppt-opc-thumbnail facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**设计取舍**
+
+渲染完全依赖外部工具链：`find_soffice()` 探测 PATH 与 macOS 应用路径，缺失即失败；PyMuPDF 在 `render_pages` 内延迟导入，缺包时报错（L75–L78）。换取的是无需自己解析/绘制幻灯片内容。另一取舍是标签映射：docstring 宣称标签让视觉发现能直接定位待编辑文件（L7–L8），但实现只按页序生成顺序标签（L121），若部件命名或顺序与线性页序不一致，该映射会失配。soffice 调用设有 300 秒超时上限以约束单次转换时长。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py:L58–L63](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py#L58-L63), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py:L121–L121](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py#L121-L121), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py:L7–L8](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py#L7-L8), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py:L68–L70](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py#L68-L70)
+
+<!-- kb:knowledge owner=feature-ppt-opc-thumbnail facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证方式**
+
+Inference / 设计推断（非作者历史意图）：
+
+所示摘录中未包含针对该脚本的测试；模块 docstring 给出两条例子调用（`thumbnail.py deck.pptx`、`... grid --cols 4`）作为用法示范（L4–L5）。代码内可观察的检查点包括：输入文件存在性检查（L114–L116）、PDF 产出与 PyMuPDF 导入检查（L72–L78），以及 CLI 边界把 `ThumbnailError` 转为非零退出的路径（L139–L140）——这些错误分支是手动运行时可复现的行为。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py:L4–L5](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py#L4-L5), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py:L114–L116](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py#L114-L116), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py:L135–L140](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/opc/thumbnail.py#L135-L140)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-ppt-system-diagram-renderer.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-ppt-system-diagram-renderer.md
new file mode 100644
index 00000000..350b8452
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-ppt-system-diagram-renderer.md
@@ -0,0 +1,46 @@
+---
+title: "PPT 系统架构图原生形状渲染引擎（system-diagram.js）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js:L797-L812, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js:L840-L873, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/components.js:L1729-L1737, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js:L130-L143, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js:L210-L224, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js:L791-L840, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js:L330-L331, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js:L480-L482, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js:L543-L549, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js:L245-L267, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js:L428-L447, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js:L46-L53, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js:L143-L158]
+feature: "ppt-system-diagram-renderer"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js", "jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/components.js"]
+---
+
+# PPT 系统架构图原生形状渲染引擎（system-diagram.js）
+
+<!-- kb:knowledge owner=feature-ppt-system-diagram-renderer facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**公共入口与调用契约**
+
+CommonJS 模块导出 renderSystemDiagram、normalizeSpec、DEFAULT_THEME 及四个 IR 构造器 item/group/bandNode/groupBand。主入口 renderSystemDiagram({ pres, slide, spec, bounds, theme }) 接收 pptxgenjs 的 presentation 与 slide、声明式 Diagram IR、目标区域和主题；缺 pres 或 slide 时抛错。渲染到既有 slide 上的一个区域（不画标题等页面装饰，宿主页自管），并返回布局描述符 { bounds, nodes, groups, edgeLabels, warnings } 供 QA 与 diagram-verifier 免解析 PPTX 检查几何。上层封装 components.js 的 addSystemDiagram 计算密度主题后转发调用。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js:L797–L812](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js#L797-L812), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js:L840–L873](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js#L840-L873), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/components.js:L1729–L1737](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/components.js#L1729-L1737)
+
+<!-- kb:knowledge owner=feature-ppt-system-diagram-renderer facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证：IR 校验、重叠检测与语义损失提示**
+
+normalizeSpec 做结构校验（band 数 2–8、叶子上限 36、重复 id、悬空边、空 group 等抛错），并对截断后的 node/item label 运行 mergeSuspect：省略检测要求剥掉尾部的「等/…/…」后仍有非空前缀，斜杠合并检测要求首尾段都含字母或数字，命中则 console.warn（不阻断渲染）。渲染后 renderSystemDiagram 对所有已定位节点两两做 rectsOverlap 检查——该函数在比较式中使用 0.02 的容差而非将矩形四边内缩——重叠者写入返回值 warnings 供 QA 与 diagram-verifier 消费。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js:L130–L143](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js#L130-L143), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js:L210–L224](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js#L210-L224), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js:L791–L840](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js#L791-L840)
+
+<!-- kb:knowledge owner=feature-ppt-system-diagram-renderer facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**网格重排与视觉角色样式**
+
+band 内的 groups 通过 gridShape 重排（组数 ≤4 时首选 4 列、否则 3 列）；nodes 不经 gridShape，而是按 band.layout 直接定列数（column 为 1、row 为全宽、缺省最多 5 列）。group 内 items 由 itemGridShape 排布：4 项及以上自动 2 列。视觉外观由 styleForVisualRole 按 visual_role（primary/factor_group/warning/action 等）映射到主题色、虚线与填充透明度。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js:L330–L331](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js#L330-L331), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js:L480–L482](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js#L480-L482), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js:L543–L549](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js#L543-L549), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js:L245–L267](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js#L245-L267)
+
+<!-- kb:knowledge owner=feature-ppt-system-diagram-renderer facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**可读性下限与 fail-loud 容量检查**
+
+引擎宁可拒绝渲染也不压扁内容：computeBandRects 检查各 band 最小高度之和加上 gapFloor 间隔（最小 gap）是否超过 bounds.h + 0.01，超出则抛 [DIAGRAM-OVER-CAPACITY]，附最占高 band 明细和有序整改建议（扩区、换骨架、拆页），并禁止缩字或删条目。ITEM_H_FLOOR/NODE_H_FLOOR 下限由测量与渲染两阶段共享，保证两阶段对盒子最小尺寸的判断一致。orientation "left_to_right" 被显式移除并抛错，注释指出该路径不测内容、稀疏内容必然留下大片空白且无警告，故 fail loud 而非静默降级。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js:L428–L447](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js#L428-L447), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js:L46–L53](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js#L46-L53), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js:L143–L158](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/system-diagram.js#L143-L158)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-pptx-structural-audit.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-pptx-structural-audit.md
new file mode 100644
index 00000000..390b22fd
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-pptx-structural-audit.md
@@ -0,0 +1,46 @@
+---
+title: "PPTX 结构与可读性审计脚本（audit_pptx.py 及配套 QA 脚本）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/audit_pptx.py:L511-L534, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/qa_density.py:L9-L18, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/qa_geometry.py:L459-L482, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/audit_pptx.py:L494-L534, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/qa_density.py:L67-L111, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/audit_pptx.py:L303-L313, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/qa_geometry.py:L1-L13, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/qa_geometry.py:L229-L253, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/qa_geometry.py:L442-L452, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/audit_pptx.py:L303-L336, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/audit_pptx.py:L344-L381, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/qa_geometry.py:L229-L279]
+feature: "pptx-structural-audit"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/audit_pptx.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/audit_pptx.py", "jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/qa_density.py", "jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/qa_geometry.py"]
+---
+
+# PPTX 结构与可读性审计脚本（audit_pptx.py 及配套 QA 脚本）
+
+<!-- kb:knowledge owner=feature-pptx-structural-audit facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证入口**
+
+所提供的输入中没有针对这三个脚本的测试文件或测试调用；可观察到的验证方式是脚本自身的退出码契约（audit_pptx.py、qa_density.py、qa_geometry.py 均在有 error 时返回 1）和结构化 JSON 报告（--report / --json），供流水线消费。qa_geometry.py 支持 --slide 单页复查，qa_density.py 的文档字符串展示了带 --lock 的流水线用法示例。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/audit_pptx.py:L511–L534](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/audit_pptx.py#L511-L534), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/qa_density.py:L9–L18](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/qa_density.py#L9-L18), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/qa_geometry.py:L459–L482](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/qa_geometry.py#L459-L482)
+
+<!-- kb:knowledge owner=feature-pptx-structural-audit facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**命令行入口、退出码与输出通道**
+
+三个脚本均以 main() 作为 CLI 入口：audit_pptx.py 接受位置参数 pptx 及 --template/--lock/--evidence-plan/--report 与三个字号阈值选项。退出码契约是"有 error 返回 1，否则 0"（audit_pptx.py L534、qa_density.py L111、qa_geometry.py L470/L482）。报告正文（含 --json 载荷）经独立 stdout logger 输出、诊断走 stderr；audit_pptx.py 的 --report 则把完整 JSON 报告写入指定文件（先建父目录），不经过 stdout。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/audit_pptx.py:L494–L534](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/audit_pptx.py#L494-L534), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/qa_density.py:L67–L111](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/qa_density.py#L67-L111), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/qa_geometry.py:L459–L482](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/qa_geometry.py#L459-L482)
+
+<!-- kb:knowledge owner=feature-pptx-structural-audit facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**独立于生成代码的包级解析流水线**
+
+三个脚本都直接用 zipfile + XML 解析打开 .pptx 包，不依赖生成代码，对任意 pptx 可运行：audit_pptx.py 用 ElementTree 读 presentation.xml 确定画布与幻灯片顺序，再逐页检查；qa_geometry.py 自述为补上人眼 contact sheet 看不见的 0.1 英寸级问题。分工上 audit_pptx.py 管包结构、模板继承计数、字号与锁契约，qa_density.py 管每页文字量，qa_geometry.py 管重叠/遮挡/越界/轴线。注意 qa_geometry.py 虽为 layout/master 继承元素设 z=-1000，但这些元素只喂给 check_duplicate_chrome，参与文字碰撞与遮挡检查的仍只是页面自身元素。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/audit_pptx.py:L303–L313](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/audit_pptx.py#L303-L313), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/qa_geometry.py:L1–L13](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/qa_geometry.py#L1-L13), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/qa_geometry.py:L229–L253](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/qa_geometry.py#L229-L253), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/qa_geometry.py:L442–L452](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/qa_geometry.py#L442-L452)
+
+<!-- kb:knowledge owner=feature-pptx-structural-audit facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**检查项与跨脚本协作**
+
+audit_pptx.py 检查必需包部件缺失、幻灯片关系指向的部件存在性；与 --template 对比时画布需精确相等，但 master/layout 数量只要求不少于模板（>=，非相等）。--evidence-plan 启用论文配图溯源：按图片字节 sha256 匹配（对 merge_slides.py 的重命名免疫），命中配图而页面文本无"来源/Source:"式来源注记则报 error。qa_geometry.py 的 check_duplicate_chrome 消费 layout/master 继承元素，抓"页面自绘页脚 + 母版继承页脚"叠加的重复 chrome，与 audit_pptx.py 中 footer_mode=master 的文本级检查互补。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/audit_pptx.py:L303–L336](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/audit_pptx.py#L303-L336), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/audit_pptx.py:L344–L381](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/audit_pptx.py#L344-L381), [jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/qa_geometry.py:L229–L279](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/ppt-creation/scripts/qa_geometry.py#L229-L279)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-rsi-dataset-folder-check.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-rsi-dataset-folder-check.md
new file mode 100644
index 00000000..fa770526
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-rsi-dataset-folder-check.md
@@ -0,0 +1,48 @@
+---
+title: "RSI 数据集任务文件夹完整性预检 check_folder.py"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/rsi-program-dataset-creator/scripts/check_folder.py:L67-L83, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/rsi-program-dataset-creator/scripts/check_folder.py:L210-L218, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/rsi-program-dataset-creator/scripts/check_folder.py:L22-L45, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/rsi-program-dataset-creator/scripts/check_folder.py:L151-L159, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/rsi-program-dataset-creator/scripts/check_folder.py:L161-L178, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/rsi-program-dataset-creator/scripts/check_folder.py:L2-L8, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/rsi-program-dataset-creator/scripts/check_folder.py:L19-L20, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/rsi-program-dataset-creator/scripts/check_folder.py:L195-L214]
+feature: "rsi-dataset-folder-check"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/rsi-program-dataset-creator/scripts/check_folder.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/rsi-program-dataset-creator/scripts/check_folder.py"]
+---
+
+# RSI 数据集任务文件夹完整性预检 check_folder.py
+
+<!-- kb:knowledge owner=feature-rsi-dataset-folder-check facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**入口与调用契约**
+
+命令行入口：`python scripts/check_folder.py <task-folder>`，恰好接收一个参数，否则打印模块 docstring 并返回 1。正常执行路径下，检测通过时输出 `ok: <root> is complete` 并返回 0；检测发现问题时把 problems 逐行输出并返回 1，warnings 仅额外打印、不影响退出码。注意契约前提：`run/scorecard.json` 在 L73 被直接 `read_text()` + `json.loads()`，此时 problems 尚未初始化，文件缺失（FileNotFoundError）或 JSON 无效会抛出未捕获异常，脚本以非零状态崩溃而非干净地返回 1；退出码契约仅在正常执行至 L214 时成立。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/rsi-program-dataset-creator/scripts/check_folder.py:L67–L83](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/rsi-program-dataset-creator/scripts/check_folder.py#L67-L83), [jiuwenswarm/resources/agent/workspace/skills/rsi-program-dataset-creator/scripts/check_folder.py:L210–L218](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/rsi-program-dataset-creator/scripts/check_folder.py#L210-L218)
+
+<!-- kb:knowledge owner=feature-rsi-dataset-folder-check facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**被校验的配置项与阈值**
+
+scorecard 顶层允许恰好 13 个键（statement、script、hash、entrypoint、evaluator_file、evaluator_command、packages、reply_format、iterations、workers、max_tokens_per_call、options、scorecard），缺失或多余的键都记为问题；options 子树只检查 7 个键（c_puct、prior_exponent、repair_attempts、completion_timeout、mode、staleness、async_ratio）是否缺失。数值硬门槛：`gateShards >= 4`、`rolloutShards <= gateShards`、`iterations >= 4*workers`、`max_tokens_per_call >= 32000`。workers>1 且 mode=serial 同样计入 problems（使退出码为 1），报错文案解释这会让运行警告后串行化、浪费 worker；workers==1 时要求 mode 为 serial。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/rsi-program-dataset-creator/scripts/check_folder.py:L22–L45](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/rsi-program-dataset-creator/scripts/check_folder.py#L22-L45), [jiuwenswarm/resources/agent/workspace/skills/rsi-program-dataset-creator/scripts/check_folder.py:L151–L159](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/rsi-program-dataset-creator/scripts/check_folder.py#L151-L159), [jiuwenswarm/resources/agent/workspace/skills/rsi-program-dataset-creator/scripts/check_folder.py:L161–L178](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/rsi-program-dataset-creator/scripts/check_folder.py#L161-L178)
+
+<!-- kb:knowledge owner=feature-rsi-dataset-folder-check facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证入口**
+
+所示片段中脚本自身的验证入口就是它的命令行执行：`python scripts/check_folder.py <task-folder>`，通过/失败以退出码 0/1 体现，问题与 `ok:` 消息经 logging 输出到 stdout（L20 配置 INFO 级、stdout 流）。它覆盖的检查面即上文各条规则（键集、seed 清单、artifact_path、数值下限、脚本文本比对等）。风险点：`run/scorecard.json` 缺失时 `read_text()` 在 `json.loads()` 之前就抛出 FileNotFoundError（L73），未捕获，脚本以 traceback 崩溃；这属于未处理的失败路径，而非干净的错误报告。所示证据中没有该脚本的单测或其他测试入口。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/rsi-program-dataset-creator/scripts/check_folder.py:L2–L8](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/rsi-program-dataset-creator/scripts/check_folder.py#L2-L8), [jiuwenswarm/resources/agent/workspace/skills/rsi-program-dataset-creator/scripts/check_folder.py:L19–L20](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/rsi-program-dataset-creator/scripts/check_folder.py#L19-L20), [jiuwenswarm/resources/agent/workspace/skills/rsi-program-dataset-creator/scripts/check_folder.py:L67–L83](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/rsi-program-dataset-creator/scripts/check_folder.py#L67-L83)
+
+<!-- kb:knowledge owner=feature-rsi-dataset-folder-check facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**取舍与边界**
+
+Inference / 设计推断（非作者历史意图）：
+
+脚本明确限定为静态预检：不导入 seed、不运行 evaluator（L6–L8 docstring 自述），因此所有门槛都是形状/数值层面的，运行时行为只能以 warnings 形式"smell"——注释 L195–L196 说明探针会拒绝 error 中不含位置的文件夹，但该行为本身无法在此测试，只以警告提示补 traceback。区分两级严重度：键集/数值/一致性违规记入 problems 并返回 1，而 traceback 启发式仅打警告不动退出码（L197–L214）。推断（inference）：这条 traceback 规则被降为警告而非问题，可能因为它是启发式判断而非确定性契约违约，但代码与注释均未给出理由。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/rsi-program-dataset-creator/scripts/check_folder.py:L2–L8](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/rsi-program-dataset-creator/scripts/check_folder.py#L2-L8), [jiuwenswarm/resources/agent/workspace/skills/rsi-program-dataset-creator/scripts/check_folder.py:L195–L214](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/rsi-program-dataset-creator/scripts/check_folder.py#L195-L214)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-skill-generator-cli.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-skill-generator-cli.md
new file mode 100644
index 00000000..e2df494a
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-skill-generator-cli.md
@@ -0,0 +1,54 @@
+---
+title: "skill-gen CLI（sop-text / url-fetch 子命令）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_generator_cli.py:L99-L124, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_generator_cli.py:L61-L96, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_generator_cli.py:L40-L44, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/router.py:L19-L41, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/__init__.py:L34-L51, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_generator_cli.py:L70-L76, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_generator_cli.py:L91-L95, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/web_page.py:L24-L28, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/router.py:L33-L37, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/router.py:L39-L41, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/web_page.py:L70-L80, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/web_page.py:L139-L141, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/wechat_article.py:L110-L115, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_generator_cli.py:L8-L13, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/web_page.py:L152-L153, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/wechat_article.py:L126-L127, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_generator_cli.py:L62-L65]
+feature: "skill-generator-cli"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_generator_cli.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_generator_cli.py", "jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/web_page.py", "jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/__init__.py", "jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/models.py", "jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/router.py", "jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/wechat_article.py"]
+---
+
+# skill-gen CLI（sop-text / url-fetch 子命令）
+
+<!-- kb:knowledge owner=feature-skill-generator-cli facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**命令行入口与子命令契约**
+
+CLI 通过 `python3 .../scripts/skill_generator_cli.py` 调用，argparse 定义两个必选子命令：`sop-text --sop-file <Path>`（可选 `--out-text`、`--print-raw-chars`）和 `url-fetch --url <str>`（可选 `--out-json`）。handler 返回 int 作为进程退出码；文件不存在或 URL 为空返回 2。`sop-text` 仅输出纯文本（复用 `skill_gen.sop_parser._extract_raw_text`），明确不产出 SOPStructure JSON；`url-fetch` 输出 `FetchedPage` 的 JSON 数组（dataclass 经 `asdict` 序列化），写到 `--out-json` 或 stdout。脚本必须以绝对路径调用，不依赖 cwd。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_generator_cli.py:L99–L124](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_generator_cli.py#L99-L124), [jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_generator_cli.py:L61–L96](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_generator_cli.py#L61-L96)
+
+<!-- kb:knowledge owner=feature-skill-generator-cli facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**分层结构与数据流**
+
+CLI 是薄壳：`main()` 配置日志并把脚本目录追加到 `sys.path` 尾部（避免遮蔽 stdlib），然后 `asyncio.run` 进入子命令 handler；重依赖（skill_gen 各模块）在 handler 内延迟导入。`url-fetch` 数据流为 CLI → `url_ingest.fetch_pages_from_url`（router）→ 按 URL 形态分发到 `fetch_wechat_article` 或 `fetch_web_page` → 各自解析 HTML 并返回 `List[FetchedPage]`（通常一个元素）。`url_ingest.__init__` 另提供 `validate_fetch_and_flatten`：先做 SSRF 校验（`check_url_allowed_for_fetch`）再抓取并拼平为单一文档字符串——CLI 路径未调用该校验，属上层组合入口。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_generator_cli.py:L40–L44](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_generator_cli.py#L40-L44), [jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/router.py:L19–L41](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/router.py#L19-L41), [jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/__init__.py:L34–L51](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/__init__.py#L34-L51)
+
+<!-- kb:knowledge owner=feature-skill-generator-cli facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**命令行参数与后端抓取默认值**
+
+`sop-text` 需要 `--sop-file`（Path），`--print-raw-chars` 优先于 `--out-text`：置位时只向 stdout 打印字符数并立即返回，不会写文件；否则有 `--out-text` 就写 UTF-8 文件，否则打印原文。`url-fetch` 需要 `--url`，有 `--out-json` 写文件、否则打印 JSON。两个后端模块各自默认 `DEFAULT_TIMEOUT = 30.0` 和 Chrome/120 User-Agent；router 仅当调用方显式传 `timeout`/`user_agent`（非 None）时才覆盖默认值。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_generator_cli.py:L70–L76](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_generator_cli.py#L70-L76), [jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_generator_cli.py:L91–L95](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_generator_cli.py#L91-L95), [jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/web_page.py:L24–L28](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/web_page.py#L24-L28), [jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/router.py:L33–L37](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/router.py#L33-L37)
+
+<!-- kb:knowledge owner=feature-skill-generator-cli facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**URL 分发与正文抽取行为**
+
+`fetch_pages_from_url` 按 URL 形态分发：匹配 `mp.weixin.qq.com` 等 `/s` 链接走 `fetch_wechat_article`，其余 HTTP(S) 走 `fetch_web_page`；通用页面在 `MAIN_CONTENT_SELECTORS` 候选中选取文本量 >100 字符的节点，失败时降级为 body 内 >200 字符的容器，最终回退到整个 body，且抽取出的正文至少 50 字符否则报错。WeChat 抓取器要求页面存在 `div#js_content` 节点，抽取为空即抛错；两者都输出单个 `FetchedPage`（含 title、source_type、metadata）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/router.py:L39–L41](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/router.py#L39-L41), [jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/web_page.py:L70–L80](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/web_page.py#L70-L80), [jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/web_page.py:L139–L141](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/web_page.py#L139-L141), [jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/wechat_article.py:L110–L115](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/wechat_article.py#L110-L115)
+
+<!-- kb:knowledge owner=feature-skill-generator-cli facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**使用示例与运行期可观测点**
+
+模块 docstring 给出两个子命令的调用模板（`/ABS/.../skill_generator_cli.py sop-text --sop-file /ABS/SOP.md [--out-text ...] [--print-raw-chars]` 与 `url-fetch --url 'https://...' [--out-json ...]`），是带占位符的示例而非可直接执行的完整命令。运行期可观测点包括：两个抓取器成功解析后通过 logger 记录 `Parsed ...: url=... title=...`（web_page.py:152、wechat_article.py:126），CLI 对文件不存在或空 URL 返回退出码 2。所示文件中未包含测试入口。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_generator_cli.py:L8–L13](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_generator_cli.py#L8-L13), [jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/web_page.py:L152–L153](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/web_page.py#L152-L153), [jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/wechat_article.py:L126–L127](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/url_ingest/wechat_article.py#L126-L127), [jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_generator_cli.py:L62–L65](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_generator_cli.py#L62-L65)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-skill-page-scrape-blocks.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-skill-page-scrape-blocks.md
new file mode 100644
index 00000000..db816064
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-skill-page-scrape-blocks.md
@@ -0,0 +1,54 @@
+---
+title: "skill-omni-creation 网页抓取到统一 Stage01 Blocks（scrape_page）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/scrape_page.py:L375-L402, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/scrape_page.py:L703-L713, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/scrape_page.py:L820-L876, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/scrape_page.py:L885-L911, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/scrape_page.py:L922-L922, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/scrape_page.py:L955-L966, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/common.py:L52-L57, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/scrape_page.py:L860-L876, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/download_images.py:L94-L95, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/download_images.py:L134-L158, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/print_blocks.py:L126-L138, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/scrape_page.py:L895-L911, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/download_images.py:L109-L115, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/environment_gate.py:L418-L424, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/download_images.py:L27-L31, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/scrape_page.py:L94-L108, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/scrape_page.py:L542-L551, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/environment_gate.py:L141-L168]
+feature: "skill-page-scrape-blocks"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/scrape_page.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/scrape_page.py", "jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/print_blocks.py", "jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/common.py", "jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/download_images.py", "jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/environment_gate.py"]
+---
+
+# skill-omni-creation 网页抓取到统一 Stage01 Blocks（scrape_page）
+
+<!-- kb:knowledge owner=feature-skill-page-scrape-blocks facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的抓取行为与依赖关系**
+
+支持：无头 Chromium 单页抓取（stealth UA、可选 playwright_stealth、cookie 横幅点掉、懒加载滚动）；统一 blocks 提取，覆盖语义标签、ARIA 角色、contenteditable/自定义编辑器、canvas、JS 渲染的 div/section/article 叶子文本，并对嵌入的 YouTube/Bilibili/Vimeo 链接做 `detect_video_urls_from_html` 归一；平台 URL 走 yt-dlp/Bilibili API 取标题后直接移交流程。外部依赖包括 Playwright+Chromium（由 environment_gate 自动修复安装）、bs4、yt-dlp 子进程和 stage_04b 视频处理、download_images 的 stage02 消费方。文档证据缺失，以上仅来自所示实现。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/scrape_page.py:L375–L402](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/scrape_page.py#L375-L402), [jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/scrape_page.py:L703–L713](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/scrape_page.py#L703-L713), [jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/scrape_page.py:L820–L876](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/scrape_page.py#L820-L876)
+
+<!-- kb:knowledge owner=feature-skill-page-scrape-blocks facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**命令行入口与退出契约**
+
+scrape_page.py 以 `main()` 为入口，接受可选位置参数 url、slug，以及 `--out`（覆盖默认的 work/<slug>/stage01.json 输出路径）和 `--check-deps`。环境门失败时退出码为 2；仅当异常从 `scrape_page()` 逃逸（如浏览器启动失败）才以退出码 4 结束，而单页加载异常在 `scrape_one_page` 内被捕获并返回空 HTML 继续。写入由 common.write_json 原子完成（tmp 文件加 os.replace）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/scrape_page.py:L885–L911](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/scrape_page.py#L885-L911), [jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/scrape_page.py:L922–L922](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/scrape_page.py#L922-L922), [jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/scrape_page.py:L955–L966](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/scrape_page.py#L955-L966), [jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/common.py:L52–L57](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/common.py#L52-L57)
+
+<!-- kb:knowledge owner=feature-skill-page-scrape-blocks facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**阶段数据流：stage01 块到下游消费**
+
+scrape_page 用 Playwright 抓单页，将 DOM 解析为统一 blocks（heading/text/image）并写入有界的 stage01.json。download_images（stage02）读取整个 stage01：仅对 image 块并发下载与去重，但所有非 image 块原样保留并连同资产清单一起写入 stage02.json。print_blocks 为 stage01/02/03 提供同一套有界代表视图（`_select_bounded_indices` + 字符预算），避免下游扩大模型可见上下文。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/scrape_page.py:L860–L876](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/scrape_page.py#L860-L876), [jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/download_images.py:L94–L95](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/download_images.py#L94-L95), [jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/download_images.py:L134–L158](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/download_images.py#L134-L158), [jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/print_blocks.py:L126–L138](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/print_blocks.py#L126-L138)
+
+<!-- kb:knowledge owner=feature-skill-page-scrape-blocks facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**依赖门与 --check-deps 自检**
+
+两个脚本都提供 `--check-deps`：只运行共享环境门（自动修复后退出），成功打印 DEPENDENCIES_OK，EnvironmentGateError 时退出码 2。Chromium 启动校验仅在 web/web-images profile 下执行——scrape_page 的 `--check-deps` 走 require_web=True 的 web profile，会验证/修复 Chromium；download_images 使用 images profile（仅 requests/Pillow），不做 Chromium 校验。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/scrape_page.py:L895–L911](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/scrape_page.py#L895-L911), [jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/download_images.py:L109–L115](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/download_images.py#L109-L115), [jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/environment_gate.py:L418–L424](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/environment_gate.py#L418-L424), [jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/download_images.py:L27–L31](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/download_images.py#L27-L31)
+
+<!-- kb:knowledge owner=feature-skill-page-scrape-blocks facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**Stage01 有界输出的常量与环境门配置**
+
+Stage01 的体量由 scrape_page.py 顶部的模块常量控制：STAGE01_MAX_BLOCKS=420、STAGE01_MAX_TOTAL_TEXT_CHARS=60_000、STAGE01_MAX_PAGE_OUTPUT_CHARS=90_000；STAGE01_MIN_TEXT_ALLOCATION=40 是加权水填充分配的基准下限参数，实际分配会被预算和原文长度截断（base = min(floor, budget//len)），并非每个保留文本块保证拿到 40 字符。另有按 format 的结构化文本上限（code/editor 4000、table 2500、definition 2000、canvas 2000、js_text 1200）。运行环境由 environment_gate 的 profile 决定（requests/images/web/web-images），解释器选择顺序为：激活的 VIRTUAL_ENV、已存在的项目 .venv、当前 venv，之后才可能自动创建项目 .venv；web/web-images profile 额外校验并自动修复 Playwright Chromium。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/scrape_page.py:L94–L108](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/scrape_page.py#L94-L108), [jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/scrape_page.py:L542–L551](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/scrape_page.py#L542-L551), [jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/environment_gate.py:L141–L168](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/environment_gate.py#L141-L168), [jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/environment_gate.py:L418–L424](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/environment_gate.py#L418-L424)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-sop-structure-extraction.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-sop-structure-extraction.md
new file mode 100644
index 00000000..a0713963
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-sop-structure-extraction.md
@@ -0,0 +1,54 @@
+---
+title: "SOP 结构化抽取（parse_sop_raw_text / parse_sop_file）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/__init__.py:L9-L21, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_parser.py:L257-L273, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_parser.py:L394-L427, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_parser.py:L275-L306, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_parser.py:L310-L341, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_chunk_merge.py:L478-L560, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_parser.py:L246-L254, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_parser.py:L279-L304, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_chunk_merge.py:L459-L468, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_parser.py:L315-L341, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_chunk_merge.py:L403-L456, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_chunk_merge.py:L537-L557, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_parser.py:L343-L347, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_parser.py:L371-L389, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_parser.py:L365-L369]
+feature: "sop-structure-extraction"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_parser.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_parser.py", "jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_chunk_merge.py", "jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_fallback.py", "jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/__init__.py", "jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/models.py"]
+---
+
+# SOP 结构化抽取（parse_sop_raw_text / parse_sop_file）
+
+<!-- kb:knowledge owner=feature-sop-structure-extraction facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**公开入口与契约**
+
+包级导出（`skill_gen/__init__.py`）暴露 `parse_sop_file`、`parse_sop_raw_text`、`DEFAULT_SINGLE_SHOT_BUDGET` 及模型和 fallback 工厂。`parse_sop_raw_text(raw_text, *, invoke_llm_json, parse_options=None, source_label="")` 是核心异步入口，必须传入 `invoke_llm_json`（完整 SOPStructure 抽取仅靠 LLM），返回 `(SOPStructure, extraction_meta)`，全文始终写入 `SOPStructure.raw_text`。`parse_sop_file(file_path, ...)` 先检查文件存在（缺失抛 `FileNotFoundError`），空文本/空抽取抛 `ValueError`。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/__init__.py:L9–L21](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/__init__.py#L9-L21), [jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_parser.py:L257–L273](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_parser.py#L257-L273), [jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_parser.py:L394–L427](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_parser.py#L394-L427)
+
+<!-- kb:knowledge owner=feature-sop-structure-extraction facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**分层抽取流程与模式选择**
+
+入口层 `parse_sop_raw_text` 校验非空文本后，按 `sop_parse_mode` 决定路径：`chunked`/`single` 直接切换，`auto` 则在「应用正的 `single_shot_budget` 上限之后的 `room_single`」与原文长度比较，超出才走分块（sop_parser.py:L275–L293）。分块路径由 `extract_structure_chunked` 做 map-reduce：按预算递归二分切块、逐块 LLM 抽取、确定性合并，多块时再跑可选 reconcile LLM 整理；单发路径 `extract_structure_single_shot` 只做一次 LLM 调用。若分块结果出现 ≥2 条空块警告，会截断原文（仅在超预算时）跑一次单发兜底，且仅当单发结果的 steps+knowledge_items+sections 计分不低于分块结果时才替换，并在 meta 标记 `replaced_by_single_shot_after_chunk_loss`（sop_parser.py:L315–L337）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_parser.py:L275–L306](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_parser.py#L275-L306), [jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_parser.py:L310–L341](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_parser.py#L310-L341), [jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_chunk_merge.py:L478–L560](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_chunk_merge.py#L478-L560)
+
+<!-- kb:knowledge owner=feature-sop-structure-extraction facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**解析选项与字符预算**
+
+`parse_options` 由 `_default_parse_options` 填充默认值：`sop_parse_mode="auto"`、`single_shot_budget=12000`、`max_chunk_chars=8000`、`chunk_overlap=1200`、`max_context_chars=120000`、`safety_margin=2000`。单发可用空间 `room_single = max(1, max_context_chars - 模板开销 - safety_margin)`，且仅当 `single_shot_budget` 为正并小于该值时进一步收紧。分块路径把非正的 `max_chunk_chars` 以 `None` 传入 `extract_structure_chunked`，`_compute_room_for_chunk` 仅在 `max_chunk_chars` 为正时用它截小房间，最终下限为 1。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_parser.py:L246–L254](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_parser.py#L246-L254), [jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_parser.py:L279–L304](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_parser.py#L279-L304), [jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_chunk_merge.py:L459–L468](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_chunk_merge.py#L459-L468)
+
+<!-- kb:knowledge owner=feature-sop-structure-extraction facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**分块合并与单发兜底的取舍**
+
+分块路径用 `merge_partial_dicts` 做确定性合并（按 step_number 去重合并、按 id 合并 sections、多数投票 sop_type，分歧时判 hybrid），多块时可用 `_RECONCILE_PROMPT` 整体替换合并稿。当 ≥2 个分块抽取为空时触发单发兜底，但替换判据仅是 steps+knowledge_items+sections 的数量总和 `score_s >= score_c`（sop_parser.py:L329–L333）——这是数量启发式，不保证单发结果质量不低于分块结果；且截断警告仅在单发被采纳时才追加（L337–L341），兜底单发本身的截断在其他路径下不记录。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_parser.py:L315–L341](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_parser.py#L315-L341), [jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_chunk_merge.py:L403–L456](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_chunk_merge.py#L403-L456), [jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_chunk_merge.py:L537–L557](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_chunk_merge.py#L537-L557)
+
+<!-- kb:knowledge owner=feature-sop-structure-extraction facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**运行时自检：空抽取与弱结果信号**
+
+两条路径都在抽取完全为空（无 steps、无 title、无 knowledge_items）时追加 `extraction_empty_after_chunked` / `extraction_empty_single_shot` 警告并抛 `ValueError`，异常消息携带 `merge_warnings`。空抽取检查之后，`weak_reasons` 仅在分块且 `chunk_count > 1` 时由四类质量信号推导：缺 title、sections ≥3 却缺 scope、长文（超过 room_single）但 knowledge_items < 3、以及未应用 reconcile；命中任一即置 `use_raw_excerpt_draft_fallback = True`。`extraction_meta.output_counts` 记录五类输出条数。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_parser.py:L343–L347](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_parser.py#L343-L347), [jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_parser.py:L371–L389](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_parser.py#L371-L389), [jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_parser.py:L365–L369](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-gen-4-enterprise-doc/scripts/skill_gen/sop_parser.py#L365-L369)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-video-coarse-scan-frame-extraction.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-video-coarse-scan-frame-extraction.md
new file mode 100644
index 00000000..928d1027
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-video-coarse-scan-frame-extraction.md
@@ -0,0 +1,64 @@
+---
+title: "analyze_video.py：视频粗扫抽帧与审核批次门控"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L307-L330, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L349-L354, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L371-L375, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L91-L117, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L152-L188, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L325-L348, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L11-L18, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L265-L287, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L359-L396, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L120-L149, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L249-L304, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L38-L49, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L307-L323, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L62-L69, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L73-L83, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L178-L210, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L230-L259, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L352-L375]
+feature: "video-coarse-scan-frame-extraction"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py"]
+---
+
+# analyze_video.py：视频粗扫抽帧与审核批次门控
+
+<!-- kb:knowledge owner=feature-video-coarse-scan-frame-extraction facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**入口与调用方式**
+
+命令行入口 `python analyze_video.py <video_url_or_slug> [--title] [--slug]`，target 为 http(s) URL 时下载视频，为 slug 时直接复用 `work/<slug>/video.mp4` 或 `downloads/video.*`。另有互斥的 `--current-review-batch` 与 `--next-review-batch`：前者仅重印当前审核批次，后者确认当前批次后前移游标，均跳过下载与抽帧。正常流程结束时初始化 `current_batch=1` 并打印第一批；抽帧为 0 帧或找不到视频时以 `sys.exit(1)` 退出。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L307–L330](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py#L307-L330), [jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L349–L354](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py#L349-L354), [jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L371–L375](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py#L371-L375)
+
+<!-- kb:knowledge owner=feature-video-coarse-scan-frame-extraction facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的行为**
+
+支持两种输入（URL 自动经 `common.resolve_work_slug_for_url` 复用 stage01 的 slug 后经 `common.download_video` 下载；slug 本地查找已完成的视频文件，跳过 `.part`）。超限帧通过 `_uniformly_cap_frames` 均匀抽样至 90 帧并重命名为连续的 `frame_NNNN.png`。审核代理采用四档递降编码尝试（480x270/q60 → 480x270/q50 → 384x216/q60 → 384x216/q50），任一档满足 45KB 即返回，否则在最小档仍超限时抛错。依赖外部 ffmpeg/ffprobe 与 `common` 模块（work 路径、下载、slug 解析）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L91–L117](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py#L91-L117), [jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L152–L188](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py#L152-L188), [jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L325–L348](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py#L325-L348)
+
+<!-- kb:knowledge owner=feature-video-coarse-scan-frame-extraction facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**设计取舍**
+
+Inference / 设计推断（非作者历史意图）：
+
+单阶段粗扫（不做细扫）换取流程简单与成本可控：用降低帧率 + 90 帧均匀上限覆盖全片，代价是长时间视频的时间分辨率下降。审核帧与原始帧分离（低分辨率有损 JPEG 代理仅供模型查看，PNG 原帧保留供最终 Skill 使用），并以每批 5 帧、字节预算（45KB/帧、225KB/批）约束模型单次上下文，代价是增加了状态文件与批次门控逻辑。门控是提示式的：输出文本明确要求 agent 只读所列文件、不扫目录，属约束引导而非硬性隔离（此句为推断，依据输出文案）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L11–L18](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py#L11-L18), [jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L265–L287](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py#L265-L287)
+
+<!-- kb:knowledge owner=feature-video-coarse-scan-frame-extraction facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**粗扫抽帧流水线与批次门控数据流**
+
+正常流程按 probe_duration → choose_fps → extract_frames → build_review_frames 顺序执行：ffprobe 读取时长，按 min(0.5fps, 90/时长) 选定帧率，ffmpeg 抽帧并经 _uniformly_cap_frames 均匀截断到 90 帧重命名为 frame_NNNN.png；随后生成低分辨率 JPEG 审核代理帧，并把 {current_batch, batch_size, total_frames} 持久化到 work/<slug>/review_batch_state.json。批次门控为提示式：_print_review_batch 只打印当前批次（每批至多 5 帧，末批可更少）的精确文件路径并要求 agent 不扫描目录，--next-review-batch 经 _load_review_state 校验后前移游标。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L359–L396](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py#L359-L396), [jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L120–L149](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py#L120-L149), [jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L249–L304](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py#L249-L304)
+
+<!-- kb:knowledge owner=feature-video-coarse-scan-frame-extraction facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**常量、命令行参数与外部超时**
+
+抽帧与审核预算为脚本内模块常量：BASE_FPS=0.5、MAX_FRAMES=90、BATCH_SIZE=5，审核代理 480x270 主档 / 384x216 回退档、JPEG 质量 60/50、单帧上限 45KB、每批上限 225KB。命令行提供 --title、--slug 以及互斥的 --current-review-batch/--next-review-batch。外部 ffmpeg/ffprobe 子进程的超时取自 common.OPERATION_TIMEOUT_SECONDS，不在本脚本内定义。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L38–L49](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py#L38-L49), [jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L307–L323](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py#L307-L323), [jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L62–L69](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py#L62-L69)
+
+<!-- kb:knowledge owner=feature-video-coarse-scan-frame-extraction facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**运行时校验与错误路径**
+
+本脚本无独立测试入口；所示证据中的验证均为运行时自检。ffprobe 返回非零、无法解析的时长或非正时长均抛 RuntimeError（L73–L83）。审核帧编码与批次预算在构建时强制执行：单帧四档尝试后仍超 45KB 抛错（L183–L187），每批超过 225KB 抛错（L203–L210）。批次门控读取时校验状态文件存在与 batch_size 匹配（L230–L246），打印批次时复核文件数与状态一致且批次号在范围内（L249–L259）。主流程对找不到已完成视频（L352–L354）与抽帧为 0（L373–L375）以 sys.exit(1) 退出。注意：ffprobe/ffmpeg 子进程仅捕获 FileNotFoundError 并在 returncode 非零时抛 RuntimeError；超时（common.OPERATION_TIMEOUT_SECONDS，L62–L69、L134–L141）未被捕获，会以 subprocess.TimeoutExpired 向上传播。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L73–L83](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py#L73-L83), [jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L178–L210](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py#L178-L210), [jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L230–L259](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py#L230-L259), [jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py:L352–L375](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/skill-omni-creation/scripts/analyze_video.py#L352-L375)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-xlsx-add-computed-column.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-xlsx-add-computed-column.md
new file mode 100644
index 00000000..4b8f2fe8
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-xlsx-add-computed-column.md
@@ -0,0 +1,54 @@
+---
+title: "XLSX Computed Column Adder (xlsx_add_column.py)"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py:L51-L65, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py:L3-L13, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py:L1-L20, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py:L52-L65, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py:L74-L78, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py:L80-L86, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py:L89-L102, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py:L104-L109, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py:L67-L78, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py:L89-L95, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py:L111-L115]
+feature: "xlsx-add-computed-column"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py"]
+---
+
+# XLSX Computed Column Adder (xlsx_add_column.py)
+
+<!-- kb:knowledge owner=feature-xlsx-add-computed-column facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**CLI 入口与参数**
+
+命令行入口：`python3 xlsx_add_column.py <workdir> --col G [--sheet ...]`。位置参数 `workdir` 是 xlsx_unpack.py 产出的解包目录，脚本原地编辑工作表 XML，需再用 xlsx_pack.py 回打包。主要选项：`--col`（必填，目标列字母）、`--sheet`（缺省取第一张表）、`--header`/`--header-row`（默认 1）、`--formula`（模板，`{row}` 替换为行号）、`--formula-rows`（如 `2:9` 闭区间）、`--total-row`/`--total-formula`、`--numfmt`、`--border-row`/`--border-style`（默认 `medium`）。成功时打印 `added column <col> on '<sheet>'` 并返回 0。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py:L51–L65](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py#L51-L65), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py:L3–L13](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py#L3-L13)
+
+<!-- kb:knowledge owner=feature-xlsx-add-computed-column facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**测试入口**
+
+本次展示的输入只包含该脚本本体（120 行，无测试文件、无 docs），未见针对 xlsx_add_column.py 的测试或验证入口，无法从所示证据描述其测试覆盖。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py:L1–L20](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py#L1-L20)
+
+<!-- kb:knowledge owner=feature-xlsx-add-computed-column facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**命令行参数与缺省值**
+
+配置全部来自命令行：位置参数 workdir（解包目录）；--col 必填（目标列字母）；--sheet 缺省为第一张表；--header-row 缺省 1；--border-style 缺省 "medium"；其余选项（--header、--formula、--formula-rows 如 "2:9" 闭区间、--total-row、--total-formula、--numfmt、--border-row）缺省为空/未启用。效果按条件生效：仅当 --numfmt 为真时才注册 numFmt，且仅当得到非零 nfid 时才创建数据单元格的 data_xf；启用 --border-row 时会额外注册顶边框，并为合计单元格构造带 numFmtId+borderId 的 total_xf。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py:L52–L65](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py#L52-L65), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py:L74–L78](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py#L74-L78)
+
+<!-- kb:knowledge owner=feature-xlsx-add-computed-column facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的行为**
+
+支持向指定列写入：表头文本（样式取自表头行同行某列的现有单元格样式索引，源列取目标列左邻列、但被限制最小为 A，源单元格不存在时则不带样式）、按 {row} 模板展开的公式单元格（--formula-rows 指定闭区间）、合计公式单元格，以及一行行宽的顶边框——边框处理会为该行每个已有单元格换成新的样式索引，同时保留其原 numFmtId。公式用 make_cell(formula=...) 写入；--numfmt 只作用于新列的公式/合计单元格。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py:L80–L86](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py#L80-L86), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py:L89–L102](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py#L89-L102), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py:L104–L109](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py#L104-L109)
+
+<!-- kb:knowledge owner=feature-xlsx-add-computed-column facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**架构：解包目录内的原地工作表编辑器**
+
+该脚本是 xlsx 技能链中的一环：输入是 xlsx_unpack.py 产出的解包目录，脚本通过 `_xlsx_common` 定位工作表（`--sheet` 缺省取第一张表）、解析 XML 并原地编辑 sheetData，最后由用户再用 xlsx_pack.py 回打包。主流程分阶段执行：先在 Styles 中注册 numFmt/xf/边框（L74–L78），随后依次写表头（L81–L86）、循环展开公式单元格（L89–L95）、写合计单元格（L98–L102），再对边框行逐单元格改写样式索引（L104–L109），最后统一 `X.sort_sheetdata(sd)` 与 `X.update_dimension(root)` 并保存样式与工作表（L111–L114）。每个写单元格动作都是对行的独立查找/创建（`X.get_or_make_row` + `X.set_cell_in_row`），而非单遍处理。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py:L3–L13](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py#L3-L13), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py:L67–L78](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py#L67-L78), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py:L89–L95](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py#L89-L95), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py:L111–L115](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_add_column.py#L111-L115)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-xlsx-doctor-selfcheck.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-xlsx-doctor-selfcheck.md
new file mode 100644
index 00000000..6b1ba3da
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-xlsx-doctor-selfcheck.md
@@ -0,0 +1,64 @@
+---
+title: "XLSX 技能环境自检（doctor.py）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py:L40-L47, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py:L109-L119, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py:L50-L71, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py:L74-L101, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py:L8-L11, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py:L115-L130, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py:L20-L37, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py:L40-L46, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py:L104-L107, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py:L115-L116, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py:L133-L134]
+feature: "xlsx-doctor-selfcheck"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py"]
+---
+
+# XLSX 技能环境自检（doctor.py）
+
+<!-- kb:knowledge owner=feature-xlsx-doctor-selfcheck facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**职责与数据流**
+
+doctor.py 是 XLSX 技能脚本目录下的独立自检工具，不依赖技能内其他模块，只做环境探测、不做修复。控制流集中在 `main()`：按序调用 `check_python`、`check_py_deps`、`check_cli`、`check_cjk_font`，四个检查函数都向同一个 `results` 列表追加 `{check, ok, detail, required}` 字典；最终以 `required and not ok` 过滤出必需项失败来决定整体 ok 与退出码，最后统一渲染为文本或 JSON。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py:L40–L47](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py#L40-L47), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py:L109–L119](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py#L109-L119)
+
+<!-- kb:knowledge owner=feature-xlsx-doctor-selfcheck facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**检查项与依赖关系**
+
+覆盖四类检查：Python 版本、三个 pip 依赖（用 importlib 实际导入并读取 `__version__`）、两个外部 CLI 工具（用 `shutil.which` 定位），以及 CJK 字体。字体检查先用 `fc-list :lang=zh family` 列出支持中文的字族（最多展示 8 个），失败时退回对全量字族列表按 `CJK_FONT_HINTS` 名称提示做大小写不敏感的子串扫描；注释说明缺字体时中文在 PNG/PDF 中会渲染成方框。这暗示该技能的渲染链路依赖 libreoffice + poppler（推断：具体消费方脚本未在本次展示中）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py:L50–L71](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py#L50-L71), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py:L74–L101](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py#L74-L101)
+
+<!-- kb:knowledge owner=feature-xlsx-doctor-selfcheck facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**入口、输出与退出码契约**
+
+doctor.py 以 shebang 脚本形式提供，文档用法为 `python3 doctor.py [--json]`，也可经 `main()` 调用；`--json` 时输出 `{ok, results}` 的机器可读 JSON（ensure_ascii=False、缩进 2），否则打印逐项 PASS/FAIL/warn 文本报表和总结行。退出码契约：所有 `required` 检查通过返回 0，任一必需项失败返回 1；可选项失败仅标记 warn，不影响退出码。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py:L8–L11](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py#L8-L11), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py:L115–L130](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py#L115-L130)
+
+<!-- kb:knowledge owner=feature-xlsx-doctor-selfcheck facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**检查清单常量与阈值位置**
+
+被检查对象由模块顶部常量定义：`PY_DEPS` 列出 openpyxl、pandas（必需）与 lxml（可选）；`CLI_TOOLS` 列出 soffice/libreoffice 与 pdftoppm/poppler-utils（均必需）；`CJK_FONT_HINTS` 给出十个体面（family）名称提示，任一命中即算有 CJK 字体。Python 版本阈值 (3, 8) 不在常量里，而是直接写在 `check_python` 的比较表达式中。命令行仅显式定义 `--json` 一个开关（ArgumentParser 默认还附带帮助行为）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py:L20–L37](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py#L20-L37), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py:L40–L46](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py#L40-L46), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py:L104–L107](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py#L104-L107)
+
+<!-- kb:knowledge owner=feature-xlsx-doctor-selfcheck facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**探测方式的取舍**
+
+Inference / 设计推断（非作者历史意图）：
+
+字体检查采取两级策略：优先 `fc-list :lang=zh family` 精确查询，无结果时退回对全量字族列表按 `CJK_FONT_HINTS` 做大小写不敏感子串扫描，两次子进程调用均设 20 秒超时且异常被吞掉——以尽力给出结果换取对 fontconfig 环境的依赖。字体缺失被标记为必需失败（退出码 1），detail 仅提示安装建议并警告中文文本在 PNG/PDF 中会渲染成方框（推断：把渲染质量问题提升为环境不达标，是面向中文场景的保守选择）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py:L74–L101](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py#L74-L101), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py:L115–L116](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py#L115-L116)
+
+<!-- kb:knowledge owner=feature-xlsx-doctor-selfcheck facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**可验证行为**
+
+脚本自身即可作为验证入口：直接运行会依次执行 Python 版本、三个 pip 依赖导入、两个 CLI 定位和 CJK 字体共四组检查，`--json` 输出逐项 `{check, ok, detail, required}`，可用于核对面板结果与退出码是否一致。本次展示的输入中未包含针对 doctor.py 的测试文件；`main()` 为普通函数，检查函数各自接收 results 列表，具备被自动化测试分别调用的形态。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py:L40–L46](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py#L40-L46), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py:L109–L119](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py#L109-L119), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py:L133–L134](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/doctor.py#L133-L134)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-xlsx-formula-check.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-xlsx-formula-check.md
new file mode 100644
index 00000000..f717b98e
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-xlsx-formula-check.md
@@ -0,0 +1,62 @@
+---
+title: "XLSX 公式静态校验（formula_check.py）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py:L5-L11, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py:L60-L79, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py:L24-L24, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py:L60-L65, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py:L9-L11, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py:L17-L22, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py:L27-L57, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py:L30-L44, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py:L49-L55, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py:L3-L11, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py:L67-L79]
+feature: "xlsx-formula-check"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py"]
+---
+
+# XLSX 公式静态校验（formula_check.py）
+
+<!-- kb:knowledge owner=feature-xlsx-formula-check facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**命令行入口与退出码**
+
+以 CLI 脚本形式提供：`python3 formula_check.py file.xlsx [--json] [--report]`，positional 参数为工作簿路径，`--json` 输出 `{"ok": bool, "issues": [...]}` 的 JSON，否则打印人类可读报告。退出码约定为 0=未发现问题、1=发现问题、2=用法错误（openpyxl 导入失败也直接 `sys.exit(2)`）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py:L5–L11](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py#L5-L11), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py:L60–L79](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py#L60-L79)
+
+<!-- kb:knowledge owner=feature-xlsx-formula-check facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**固定的错误令牌表**
+
+唯一的配置点是模块级常量 `ERROR_TOKENS`，硬编码七个 Excel 错误令牌：`#REF!`、`#DIV/0!`、`#VALUE!`、`#N/A`、`#NAME?`、`#NULL!`、`#NUM!`，无环境变量或配置文件，不支持用户扩展。命令行仅有 `--json`/`--report` 两个布尔开关（`--report` 解析后未在代码中被使用）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py:L24–L24](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py#L24-L24), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py:L60–L65](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py#L60-L65)
+
+<!-- kb:knowledge owner=feature-xlsx-formula-check facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的检测范围与依赖**
+
+检测缓存值和公式文本中的 Excel 错误令牌，是纯静态检查，不执行公式；docstring 明确指出如需新鲜缓存值应先运行同目录的 `libreoffice_recalc.py`。依赖 openpyxl（`load_workbook`、`get_column_letter`），缺失时打印 stderr 提示并以退出码 2 结束。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py:L9–L11](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py#L9-L11), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py:L17–L22](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py#L17-L22)
+
+<!-- kb:knowledge owner=feature-xlsx-formula-check facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**扫描与输出的分层**
+
+脚本由 `_scan(path)` 与 `main()` 两层组成。`_scan` 对同一工作簿做两遍遍历：先用 `load_workbook(data_only=True)` 扫描缓存值，再用 `data_only=False` 扫描以 `=` 开头的公式文本，命中 `ERROR_TOKENS` 时收集 `{sheet, cell, type, detail}` 问题项（L27–L57）。`main()` 负责解析 `--json`/`--report` 参数、调用 `_scan`（L67）、据 `len(issues) == 0` 判定结果（L68）并按 JSON 或人类可读格式输出、返回 0/1 退出码（L69–L79）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py:L27–L57](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py#L27-L57), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py:L60–L79](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py#L60-L79)
+
+<!-- kb:knowledge owner=feature-xlsx-formula-check facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**子串匹配与双遍扫描的代价**
+
+检测采用纯静态的子串包含判断（`tok in v`）：只要字符串值或公式文本中包含任一错误令牌即报告，因此像包含 "#N/A" 的普通文本会被当作命中，存在误报的可能（L35–L41、L49–L55）。为同时覆盖缓存值和公式文本，脚本以两个不同的 `data_only` 设置、均 `read_only=True` 打开文件并各遍历一次（L30、L44），换取简单性，代价是需要两遍遍历。错误令牌表为硬编码常量，不可配置（L24）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py:L30–L44](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py#L30-L44), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py:L49–L55](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py#L49-L55)
+
+<!-- kb:knowledge owner=feature-xlsx-formula-check facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**可观察的验证行为**
+
+脚本自身通过退出码与输出暴露结果：未发现问题时退出码 0，发现问题退出码 1，docstring 另约定 2 为用法错误（L9，L79）。`--json` 时输出 `{"ok": bool, "issues": [...]}` 结构化结果（L69–L70），人类可读模式逐条打印 `[type] sheet!cell -> detail`（L75–L78）。所提供的文件中未展示针对该脚本的自动化测试入口；本条仅描述脚本内可观察的验证行为。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py:L3–L11](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py#L3-L11), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py:L67–L79](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/formula_check.py#L67-L79)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-xlsx-insert-row.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-xlsx-insert-row.md
new file mode 100644
index 00000000..2cc98375
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-xlsx-insert-row.md
@@ -0,0 +1,56 @@
+---
+title: "XLSX Row Insert with Range Extension（jiuwenswarm skills/xlsx 脚本）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/_xlsx_common.py:L57-L77, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_insert_row.py:L66-L89, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/_xlsx_common.py:L3-L7, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_insert_row.py:L52-L60, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/_xlsx_common.py:L96-L113, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_insert_row.py:L5-L20, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_shift_rows.py:L9-L12, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_insert_row.py:L66-L85, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/_xlsx_common.py:L154-L169, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_insert_row.py:L14-L20, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/_xlsx_common.py:L179-L196, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/_xlsx_common.py:L142-L157, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_insert_row.py:L5-L7]
+feature: "xlsx-insert-row"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_insert_row.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_insert_row.py", "jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_shift_rows.py", "jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/_xlsx_common.py"]
+---
+
+# XLSX Row Insert with Range Extension（jiuwenswarm skills/xlsx 脚本）
+
+<!-- kb:knowledge owner=feature-xlsx-insert-row facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**架构：分层与数据流**
+
+三层结构：xlsx_insert_row.py 是面向用户的编排层，xlsx_shift_rows.py 是薄 CLI 包装，共享逻辑集中在 _xlsx_common.py。数据流为：workbook.xml 按表名查 r:id，再到 workbook.xml.rels 解析出 worksheet XML 路径（支持绝对/相对 Target）；随后依次 shift_rows → extend_ranges → get_or_make_row → 写入新单元格 → sort_sheetdata → update_dimension → 原位写回。所有编辑直接作用于解包目录里的 XML，宣称对未触碰单元格零格式损失。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/_xlsx_common.py:L57–L77](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/_xlsx_common.py#L57-L77), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_insert_row.py:L66–L89](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_insert_row.py#L66-L89), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/_xlsx_common.py:L3–L7](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/_xlsx_common.py#L3-L7)
+
+<!-- kb:knowledge owner=feature-xlsx-insert-row facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**配置：参数与默认值**
+
+本组件无配置文件，行为完全由 CLI 参数决定。--at 为必需整数；--sheet 缺省时取 workbook.xml 中第一个 sheet（first_sheet_name，找不到表时 SystemExit）；--text/--values/--formula 缺省为空列表；--copy-style-from 缺省为 None（不加样式属性 s）。文本单元格写成 inlineStr 并保留空白，数值写 <v>，公式的等号前缀被去掉后写入 <f>。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_insert_row.py:L52–L60](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_insert_row.py#L52-L60), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/_xlsx_common.py:L96–L113](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/_xlsx_common.py#L96-L113)
+
+<!-- kb:knowledge owner=feature-xlsx-insert-row facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证：文档要求的外部校验**
+
+所示片段中没有这些脚本的自动化测试入口；验证方式是流程性的：xlsx_insert_row.py 的文档要求编辑后用 xlsx_pack.py 重新打包并校验，且因单单元格引用不被范围扩展覆盖、xlsx_shift_rows.py 不改写公式文本，两个脚本都明确提示“总是事后验证（Always validate afterwards）”。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_insert_row.py:L5–L20](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_insert_row.py#L5-L20), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_shift_rows.py:L9–L12](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_shift_rows.py#L9-L12)
+
+<!-- kb:knowledge owner=feature-xlsx-insert-row facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**功能：插行、条件性样式复制与尽力而为的范围扩展**
+
+插入流程在写新单元格前先 shift_rows 腾位并调用 extend_ranges。范围扩展是尽力而为：只对公式文本中 A1:B9 形态的范围端点按行号 >= at 加 delta，单单元格引用不动，文档要求事后核对合计值。样式复制仅在显式传入 --copy-style-from 时发生（按同列读取源行单元格的 s 属性）；未提供时新单元格不带 s 属性。写回前会重排行列并调用 update_dimension，而它只在 dimension 元素已存在且 maxr>0 时更新 @ref。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_insert_row.py:L66–L85](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_insert_row.py#L66-L85), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/_xlsx_common.py:L154–L169](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/_xlsx_common.py#L154-L169), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_insert_row.py:L14–L20](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_insert_row.py#L14-L20), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/_xlsx_common.py:L179–L196](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/_xlsx_common.py#L179-L196)
+
+<!-- kb:knowledge owner=feature-xlsx-insert-row facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**取舍：直接编辑 XML 的得失**
+
+Inference / 设计推断（非作者历史意图）：
+
+脚本选择直接用 lxml 原位编辑解包目录中的 worksheet XML，模块文档声称对未触碰的单元格零格式损失；代价是公式改写只覆盖范围形态（_RANGE 正则），shift_rows 只改 row@r/cell@r 而不重写公式文本，因此两个脚本的文档都要求编辑后校验。这些是所示源码呈现的边界；将其解读为有意保守的设计选择属于推断，所示证据未包含设计历史。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/_xlsx_common.py:L3–L7](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/_xlsx_common.py#L3-L7), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/_xlsx_common.py:L142–L157](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/_xlsx_common.py#L142-L157), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_shift_rows.py:L9–L12](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_shift_rows.py#L9-L12), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_insert_row.py:L5–L7](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_insert_row.py#L5-L7)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-xlsx-reader-structural-diff.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-xlsx-reader-structural-diff.md
new file mode 100644
index 00000000..4ea07f23
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-xlsx-reader-structural-diff.md
@@ -0,0 +1,54 @@
+---
+title: "XLSX 只读结构读取器与编辑损伤差分（xlsx_reader.py）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py:L32-L50, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py:L104-L141, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py:L156-L163, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py:L81-L99, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py:L109-L124, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py:L67-L78, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py:L136-L139, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py:L176-L177, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py:L165-L178, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py:L32-L44, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py:L116-L119, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py:L138-L139]
+feature: "xlsx-reader-structural-diff"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py"]
+---
+
+# XLSX 只读结构读取器与编辑损伤差分（xlsx_reader.py）
+
+<!-- kb:knowledge owner=feature-xlsx-reader-structural-diff facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**只读双通道：原始 zip 探测 + openpyxl 解析**
+
+数据流分两条通道：`_zip_features` 直接读 zip 包文件名来判定宏、透视表/缓存、图表、sharedStrings、calcChain 等部件是否存在（不解析 XML，作者注释称 robust）；`describe` 再用 `load_workbook(read_only=True)` 补充表名、行列数、sheet 状态与命名区域。差分模式 `diff_against` 对新旧文件各跑一次 `describe` 做结构对比，再调用 `_sheet_sample` 做单元格采样对比，全程不写任何文件。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py:L32–L50](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py#L32-L50), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py:L104–L141](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py#L104-L141)
+
+<!-- kb:knowledge owner=feature-xlsx-reader-structural-diff facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**CLI 选项与采样上限**
+
+配置全部来自命令行：`--preview` 默认 0（关闭预览），`--json` 切换 JSON 输出，`--diff-against` 指定旧文件（L156–L163）。`_sheet_sample` 的采样上限硬编码为默认参数 `max_sheets=50`、`max_cells=200`（每个工作表最多收集 200 个非空单元格，且只遍历前 50 张表）（L81–L99）。diff 的判定范围由代码固定：工作表名称及顺序变化、三个特征位（宏、透视表、图表）丢失、命名范围被删除，以及尽力而为的单元格样本比较（L109–L139）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py:L156–L163](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py#L156-L163), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py:L81–L99](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py#L81-L99), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py:L109–L124](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py#L109-L124)
+
+<!-- kb:knowledge owner=feature-xlsx-reader-structural-diff facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**只读结构发现与损伤差分**
+
+两条只读通道：`_zip_features` 直接读 zip 文件名判定宏、透视表/缓存、图表、sharedStrings、calcChain 等部件存在性（L32–L44）；`describe`/`preview` 用 openpyxl `read_only=True` 补充表名、行列数、sheet 状态、命名区域与预览（L47–L78），全程不写文件。`--diff-against` 比较新旧文件的结构与单元格样本：预览用 `data_only=True` 读取的是文件中已缓存的公式结果值而非重新计算（L68）；样本变更列表在 JSON 报告中截断为 100 条（L136），纯文本输出下最多展示 20 条（L176–L177）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py:L32–L50](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py#L32-L50), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py:L67–L78](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py#L67-L78), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py:L136–L139](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py#L136-L139), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py:L176–L177](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py#L176-L177)
+
+<!-- kb:knowledge owner=feature-xlsx-reader-structural-diff facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证方式：退出码与输出形态**
+
+diff 模式的验证信号是退出码：`ok` 为真返回 0，否则返回 1（L178）。文本输出分支会打印 `RESULT: OK.../PROBLEMS FOUND` 以及 issues、notes 和最多 20 条样本变更（L170–L177）；但 `--json` 分支只输出 JSON 报告，不打印 RESULT 文本（L167–L168）。因此自动化校验应依赖退出码或 JSON 的 `ok` 字段，而非 RESULT 文本。所提供的材料中未包含该脚本的测试文件。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py:L165–L178](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py#L165-L178)
+
+<!-- kb:knowledge owner=feature-xlsx-reader-structural-diff facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**zip 探测的取舍与有限的特征丢失检查**
+
+结构探测用 `_zip_features` 直接读 zip 文件名而非解析 XML，作者注释称 robust（无解析开销/风险），代价是只能判断部件存在性（L32–L44）。差分只对三个特征位——宏、透视表、图表——检查"旧有新无"并计入 issues；其余已探测部件（透视缓存、sharedStrings、calcChain 等）丢失不会触发问题报告（L116–L119）。单元格对比是尽力而为的采样：默认每表最多 200 个非空单元格、前 50 张表（L81–L99），且异常时降级为 notes 而非失败（L138–L139），因此大表超出采样范围的损伤可能漏检。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py:L32–L44](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py#L32-L44), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py:L116–L119](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py#L116-L119), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py:L81–L99](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py#L81-L99), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py:L138–L139](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_reader.py#L138-L139)
+
diff --git a/knowledge/repos/jiuwenswarm/components/config-resources/feature-xlsx-workbook-unpack-repack.md b/knowledge/repos/jiuwenswarm/components/config-resources/feature-xlsx-workbook-unpack-repack.md
new file mode 100644
index 00000000..e3af1207
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/config-resources/feature-xlsx-workbook-unpack-repack.md
@@ -0,0 +1,62 @@
+---
+title: "XLSX Skill 格式保留解包/重打包（xlsx_unpack.py / xlsx_pack.py）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_unpack.py:L16-L28, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_pack.py:L30-L54, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_unpack.py:L3-L9, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_unpack.py:L24-L37, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_pack.py:L38-L52, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_pack.py:L8-L11, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_pack.py:L44-L52, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_unpack.py:L29-L37, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_unpack.py:L5-L9, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_pack.py:L5-L6, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_unpack.py:L20-L26, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_unpack.py:L21-L37, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_pack.py:L35-L47, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_pack.py:L8-L15, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_pack.py:L22-L27, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_pack.py:L47-L52]
+feature: "xlsx-workbook-unpack-repack"
+entry_points: ["jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_pack.py", "jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_unpack.py"]
+source_globs: ["jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_pack.py", "jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_unpack.py"]
+---
+
+# XLSX Skill 格式保留解包/重打包（xlsx_unpack.py / xlsx_pack.py）
+
+<!-- kb:knowledge owner=feature-xlsx-workbook-unpack-repack facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**命令行入口与退出码**
+
+两个脚本都是无依赖第三方库的 Python 3 命令行工具。`xlsx_unpack.py INPUT.xlsx OUTDIR/` 将工作簿解包到目录，参数数目不符时向 stderr 输出 usage 并返回 2，输入不是 zip 时返回 1，成功返回 0 并打印解包的 part 数量。`xlsx_pack.py SRCDIR/ OUTPUT.xlsx` 将目录重打包为 .xlsx/.xlsm，同样以参数数目（返回 2）和源目录不存在（返回 1）作为错误契约，成功时打印打包 part 数。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_unpack.py:L16–L28](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_unpack.py#L16-L28), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_pack.py:L30–L54](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_pack.py#L30-L54)
+
+<!-- kb:knowledge owner=feature-xlsx-workbook-unpack-repack facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**解包-编辑-重打包的管道结构**
+
+组件是围绕 ZIP-of-XML 这一 xlsx 本质的薄封装：解包侧用 `zipfile.ZipFile.extractall` 原样展开所有 part，收集 namelist 并检测 VBA 宏、pivotTable、图表等特殊 part 并提示保留；编辑发生在解包后的目录中（UTF-8 XML 直接修改），重打包侧用 `os.walk` 收集文件、把相对路径转为 zip 归档路径后写入。两脚本之间只通过目录内容和 `[Content_Types].xml` 等包结构约定耦合，是 openpyxl 往返（round-trip）的格式保留替代方案。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_unpack.py:L3–L9](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_unpack.py#L3-L9), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_unpack.py:L24–L37](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_unpack.py#L24-L37), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_pack.py:L38–L52](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_pack.py#L38-L52)
+
+<!-- kb:knowledge owner=feature-xlsx-workbook-unpack-repack facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**包完整性与宏保留**
+
+重打包时按 `_order_key` 排序，先写 `[Content_Types].xml`，再写 `_rels/`，其余 part 最后，以维持包完整性；`vbaProject.bin` 使用 ZIP_STORED 不压缩存储以免宏失效，其他 part 一律 ZIP_DEFLATED。解包时会检测 `xl/vbaProject.bin`、含 pivotTable 的 part 和 `xl/charts/` 前缀，并输出 "NOTE: preserve these on repack" 提示。缺 `[Content_Types].xml` 时仅打印 WARNING 仍继续打包。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_pack.py:L8–L11](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_pack.py#L8-L11), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_pack.py:L44–L52](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_pack.py#L44-L52), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_unpack.py:L29–L37](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_unpack.py#L29-L37)
+
+<!-- kb:knowledge owner=feature-xlsx-workbook-unpack-repack facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**配置面：无配置项，仅命令行位置参数**
+
+两个脚本都没有配置文件、环境变量或选项开关；全部行为通过两个位置参数控制。`xlsx_unpack.py INPUT.xlsx OUTDIR/` 中 OUTDIR 不存在时会用 `os.makedirs(outdir, exist_ok=True)` 自动创建；`xlsx_pack.py SRCDIR/ OUTPUT.xlsx` 的输出后缀（.xlsx/.xlsm）由调用者直接给定，脚本不区分。其余行为（写入顺序、vbaProject.bin 的压缩方式）是脚本内固定的启发式，不可配置。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_unpack.py:L5–L9](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_unpack.py#L5-L9), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_pack.py:L5–L6](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_pack.py#L5-L6), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_unpack.py:L20–L26](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_unpack.py#L20-L26)
+
+<!-- kb:knowledge owner=feature-xlsx-workbook-unpack-repack facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**内置验证：结构前提检查与人工提示**
+
+解包前用 `zipfile.is_zipfile(src)` 验证输入确为 zip/xlsx，否则报错退出 1；解包后扫描 namelist，对 `xl/vbaProject.bin`、含 pivotTable 的 part、`xl/charts/` 前缀输出 "NOTE: preserve these on repack" 提示。重打包侧检查 SRCDIR 是目录（否则退出 1），并在 `[Content_Types].xml` 缺失时打印 WARNING 但继续写出 ZIP。所示文件不含自动化测试入口。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_unpack.py:L21–L37](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_unpack.py#L21-L37), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_pack.py:L35–L47](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_pack.py#L35-L47)
+
+<!-- kb:knowledge owner=feature-xlsx-workbook-unpack-repack facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**以包结构启发式换取格式保留，代价是派生索引需人工维护**
+
+组件选择直接操作 ZIP-of-XML 而非 openpyxl 往返，以换取格式保留（xlsx_unpack.py:L9 明确称之为 format-preserving alternative）。重打包侧用固定启发式维持包完整性：`_order_key` 先写 `[Content_Types].xml` 再写 `_rels/`（xlsx_pack.py:L22–L27、L47），`vbaProject.bin` 以 ZIP_STORED 存储以免宏失效，其余 part 一律 ZIP_DEFLATED（L51）。成本是脚本不重算 sharedStrings 计数、不重建 calcChain，需要编辑者在解包目录中自行处理（L13–L14）；新增的公式单元格若没有缓存 `<v>`，则依赖 Excel 打开时重算或用 libreoffice_recalc.py（L14–L15）。
+
+Sources / 来源：[jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_unpack.py:L3–L9](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_unpack.py#L3-L9), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_pack.py:L8–L15](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_pack.py#L8-L15), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_pack.py:L22–L27](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_pack.py#L22-L27), [jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_pack.py:L47–L52](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/resources/agent/workspace/skills/xlsx/scripts/xlsx_pack.py#L47-L52)
+
diff --git a/knowledge/repos/jiuwenswarm/components/cron-scheduling/_index.md b/knowledge/repos/jiuwenswarm/components/cron-scheduling/_index.md
index 5cbb670d..3a46acae 100644
--- a/knowledge/repos/jiuwenswarm/components/cron-scheduling/_index.md
+++ b/knowledge/repos/jiuwenswarm/components/cron-scheduling/_index.md
@@ -42,3 +42,4 @@ sources: []
 - [cron-scheduling 源码接口与集成边界 01](source-contracts-01.md)
 
 - [定时任务与调度存储：实现深读](feature-depth-cron.md)
+- [cron-scheduling：CronJob 模型、双后端存储与投递路由](knowledge.md)
diff --git a/knowledge/repos/jiuwenswarm/components/cron-scheduling/feature-cron.md b/knowledge/repos/jiuwenswarm/components/cron-scheduling/feature-cron.md
index 7f1e89b1..15fd18bc 100644
--- a/knowledge/repos/jiuwenswarm/components/cron-scheduling/feature-cron.md
+++ b/knowledge/repos/jiuwenswarm/components/cron-scheduling/feature-cron.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/定时任务.md
 feature: "cron"
 entry_points: ["jiuwenswarm/runtime/cron/factory.py"]
-source_globs: ["jiuwenswarm/runtime/cron/factory.py", "jiuwenswarm/runtime/cron/*.py"]
+source_globs: ["jiuwenswarm/runtime/cron/factory.py", "jiuwenswarm/runtime/cron/*.py", "jiuwenswarm/gateway/message_handler/message_handler.py", "jiuwenswarm/gateway/cron/controller.py", "jiuwenswarm/agents/harness/common/tools/cron/cron_tools.py", "jiuwenswarm/agents/harness/common/tools/cron/cron_runtime.py", "jiuwenswarm/gateway/channel_manager/channel_manager.py", "jiuwenswarm/channels/web/frontend/src/components/CronPanel/cronExprValidation.ts", "jiuwenswarm/runtime/cron/cron_expr.py", "jiuwenswarm/runtime/cron/store.py", "jiuwenswarm/gateway/cron/scheduler.py", "jiuwenswarm/server/runtime/agent_adapter/team_helpers.py", "jiuwenswarm/runtime/cron/models.py", "jiuwenswarm/runtime/cron/cron_job_mutations.py", "jiuwenswarm/gateway/cron/cron_json_convert.py", "jiuwenswarm/gateway/cron/lifecycle_owners.py", "jiuwenswarm/channels/web/frontend/src/components/CronPanel/ModeSelector.tsx", "jiuwenswarm/channels/web/frontend/src/components/CronPanel/index.tsx", "jiuwenswarm/server/runtime/session/project_store.py", "jiuwenswarm/channels/web/frontend/src/components/CronPanel/cronProjectDisplay.ts", "jiuwenswarm/gateway/cron/cron_expr.py", "jiuwenswarm/gateway/cron/dingtalk_routing.py", "jiuwenswarm/gateway/cron/factory.py", "jiuwenswarm/gateway/cron/models.py", "jiuwenswarm/runtime/cron/__init__.py", "jiuwenswarm/channels/web/frontend/src/components/CronPanel/ScheduleEditor.tsx", "jiuwenswarm/channels/web/frontend/src/components/CronPanel/ConfirmDialog.tsx", "jiuwenswarm/channels/web/frontend/src/components/CronPanel/DatePicker.tsx", "jiuwenswarm/channels/web/frontend/src/components/CronPanel/SimpleSelect.tsx", "jiuwenswarm/channels/web/frontend/src/components/CronPanel/TimePicker.tsx", "jiuwenswarm/channels/web/frontend/src/components/CronPanel/scheduleConvert.ts", "jiuwenswarm/server/control/store/project_queries.py", "jiuwenswarm/common/cron_session.py", "jiuwenswarm/runtime/cron/etcd_store.py", "jiuwenswarm/runtime/cron/store_base.py", "jiuwenswarm/gateway/cron/store.py", "jiuwenswarm/gateway/cron/store_base.py", "jiuwenswarm/channels/web/frontend/src/components/CronPanel/CronTaskDrawer.tsx", "jiuwenswarm/channels/web/frontend/src/components/CronPanel/StatusBadge.tsx", "jiuwenswarm/channels/web/frontend/src/components/CronPanel/cronMode.ts", "jiuwenswarm/common/cron_team_completion.py", "jiuwenswarm/channels/web/frontend/src/components/CronPanel/cronWakeOffset.ts", "jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py", "jiuwenswarm/channels/web/frontend/src/components/CronPanel/cronWeekAlpha.ts", "jiuwenswarm/runtime/cron/dingtalk_routing.py", "jiuwenswarm/server/agent_ws_server.py", "jiuwenswarm/gateway/cron/proactive_cron_sync.py", "jiuwenswarm/agents/swarm/providers/runtime_tools.py", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/cron.ts", "jiuwenswarm/gateway/channel_manager/tui/tui_connect.py", "jiuwenswarm/channels/web/frontend/src/stores/cronStore.ts", "jiuwenswarm/channels/web/frontend/src/components/CronPanel/xiaoyiCronTarget.ts"]
 ---
 
 # 定时任务与调度存储 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/cron-scheduling/knowledge.md b/knowledge/repos/jiuwenswarm/components/cron-scheduling/knowledge.md
new file mode 100644
index 00000000..77f793a8
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/cron-scheduling/knowledge.md
@@ -0,0 +1,43 @@
+---
+title: "cron-scheduling：CronJob 模型、双后端存储与投递路由"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/cron/store_base.py:L11-L70, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/cron/__init__.py:L1-L6, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/cron/factory.py:L54-L84, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/cron/store.py:L139-L170, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/cron/models.py:L80-L114, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/cron/cron_job_mutations.py:L26-L46, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/cron/models.py:L239-L264, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/cron/dingtalk_routing.py:L44-L66, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/cron/factory.py:L32-L51, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/cron/factory.py:L70-L84, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/cron/models.py:L175-L190, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/cron/models.py:L477-L540, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/cron/cron_expr.py:L55-L76, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/cron/cron_job_mutations.py:L120-L136, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/runtime/cron/cron_job_mutations.py:L221-L222]
+---
+
+# cron-scheduling：CronJob 模型、双后端存储与投递路由
+
+<!-- kb:knowledge owner=cron-scheduling facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**传输无关的任务模型与可替换持久化后端**
+
+jiuwenswarm/runtime/cron 是传输中立（transport-neutral）的定时任务模型与持久化包：models.py 定义 CronJob/CronRunState/CronTarget 数据类与校验、cron_expr.py 负责 5/7 段表达式归一，持久化由 CronJobStoreBackend 协议抽象，FileCronJobStore（本地 JSON，supports_watch=False）与 EtcdCronJobStore（ appliance 主备 Gateway，supports_watch=True）是两个实现；包出口 __init__ 只导出 CronJob、CronJobStore、CronRunState、CronTargetChannel。CronRunState 明确不在持久化协议内（仅内存）。工厂 create_gateway_cron_store 按配置返回后端，Gateway 是唯一持久化入口，Runtime 侧 cron 工具经 build_job 产出同一份已校验的线上表示后提交变更。
+
+Sources / 来源：[jiuwenswarm/runtime/cron/store_base.py:L11–L70](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/cron/store_base.py#L11-L70), [jiuwenswarm/runtime/cron/__init__.py:L1–L6](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/cron/__init__.py#L1-L6), [jiuwenswarm/runtime/cron/factory.py:L54–L84](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/cron/factory.py#L54-L84), [jiuwenswarm/runtime/cron/store.py:L139–L170](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/cron/store.py#L139-L170)
+
+<!-- kb:knowledge owner=cron-scheduling facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**模式归一、proactive 保护、模型解析与 IM 投递绑定**
+
+任务支持 agent/team 及三段命名（agent.work.normal 等）共 20 余种 mode；特殊 mode "proactive.tick" 由 proactive_cron_sync 自动注册，其任务受保护——delete（非 force）抛 _ProactiveJobProtected，update 只允许 cron_expr/timezone/expired/updated_at 字段。模型经 resolve_cron_model 按 config → zen → login 顺序解析到规范 model_name，login 来源触发凭据绑定（CronJob.credential_ref 只认服务端登录会话派生的句柄）。投递侧 dingtalk_routing 把 originating 会话编码为 "dingtalk::{conv}::{sender}::{type}" 存入 session_id，内部会话 ID 前缀（dingtalk_ 等）不会被误当 staffId。
+
+Sources / 来源：[jiuwenswarm/runtime/cron/models.py:L80–L114](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/cron/models.py#L80-L114), [jiuwenswarm/runtime/cron/cron_job_mutations.py:L26–L46](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/cron/cron_job_mutations.py#L26-L46), [jiuwenswarm/runtime/cron/models.py:L239–L264](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/cron/models.py#L239-L264), [jiuwenswarm/runtime/cron/dingtalk_routing.py:L44–L66](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/cron/dingtalk_routing.py#L44-L66)
+
+<!-- kb:knowledge owner=cron-scheduling facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**后端选择配置与任务元数据暴露**
+
+工厂读取 `gateway.cron.store_backend`：未设置或空白时默认 "file"（值经 strip().lower() 归一）；仅当归一后等于 "etcd" 才构造 EtcdCronJobStore，其他任何值（含未知字符串，其原样保留在 CronStoreSettings.backend 中）都返回 FileCronJobStore——即选择 file 存储，而不是把值改写为 "file"。`etcd_endpoints` 接受列表/元组或逗号分隔字符串，逐项 strip 后丢弃空项；`etcd_prefix` 缺省为 "/jiuwenswarm/cron/jobs/"。`cron_job_metadata()` 向客户端暴露 modes、default_mode、default_timeout_seconds、default_team_timeout_seconds 与 max_timeout_seconds；它不包含 name/description 长度上限（64/500）或最小超时 60 秒，这些仅由常量与校验函数体现。
+
+Sources / 来源：[jiuwenswarm/runtime/cron/factory.py:L32–L51](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/cron/factory.py#L32-L51), [jiuwenswarm/runtime/cron/factory.py:L70–L84](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/cron/factory.py#L70-L84), [jiuwenswarm/runtime/cron/models.py:L175–L190](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/cron/models.py#L175-L190)
+
+<!-- kb:knowledge owner=cron-scheduling facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**往返校验与损坏条目的隔离**
+
+CronJob.from_dict 逐字段规整并校验（id/name/cron_expr/timezone/targets 必填、长度上限、wake_offset_seconds 与 timeout_seconds 范围），并在第 536 行调用 validate_cron_expression(cron_expr, timezone=timezone)；后者用 croniter 校验语法后直接调用 `ZoneInfo(timezone)`，无效时区的异常未被转换为 ValueError。parse_cron_jobs 对非 dict 条目静默跳过；dict 条目若 from_dict 抛错则记 warning 并跳过，使单条损坏数据不会拖垮整个调度列表。往返校验存在两处：构建路径用 `CronJob.from_dict(job.to_dict())`，patch 路径用 `CronJob.from_dict(updated.to_dict())`。
+
+Sources / 来源：[jiuwenswarm/runtime/cron/models.py:L477–L540](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/cron/models.py#L477-L540), [jiuwenswarm/runtime/cron/cron_expr.py:L55–L76](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/cron/cron_expr.py#L55-L76), [jiuwenswarm/runtime/cron/cron_job_mutations.py:L120–L136](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/cron/cron_job_mutations.py#L120-L136), [jiuwenswarm/runtime/cron/cron_job_mutations.py:L221–L222](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/runtime/cron/cron_job_mutations.py#L221-L222)
+
diff --git a/knowledge/repos/jiuwenswarm/components/extensions-plugins/_index.md b/knowledge/repos/jiuwenswarm/components/extensions-plugins/_index.md
index 9742c6d8..b23204be 100644
--- a/knowledge/repos/jiuwenswarm/components/extensions-plugins/_index.md
+++ b/knowledge/repos/jiuwenswarm/components/extensions-plugins/_index.md
@@ -22,6 +22,7 @@ sources: []
 |---|---|---|
 | extension、扩展、plugin、应用插件、hook、registry、loader、manifest、yuanrong、openYuanRong、cl… | 入口 | `jiuwenswarm/extensions/agent_client/`、`jiuwenswarm/extensions/application_host.py`、`jiuwenswarm/extensions/callback_compat.py` |
 
+
 - [video_duplex 全双工扩展审查规则：任务检查点、授权投递与 Provider 协议](rules.md)
 
 ## 验证入口
@@ -48,3 +49,8 @@ sources: []
 - [生命周期 Hooks 与扩展：实现深读](feature-depth-hooks.md)
 - [Application Plugin 与前端贡献：实现深读](feature-depth-applications.md)
 - [音视频双工扩展：实现深读](feature-depth-video-duplex.md)
+- [AgentOS 沙箱创建与幂等对账（jiuwenswarm agentos_router）](feature-agentos-sandbox-create-lifecycle.md)
+- [Voice/Video Duplex Managed Agent Task Service（持久队列、并发与不确定性语义）](feature-video-agent-managed-task-service.md)
+- [YuanRong FaaS 函数调用（非流式 + SSE 流式）](feature-yuanrong-faas-invocation.md)
+- [jiuwenswarm 扩展与插件：video_duplex 实时音视频 RPC 与 AgentOS Router 客户端](knowledge.md)
+- [YuanRong Agent 容器文件传输（上传/下载/列举/建目录）](feature-yuanrong-agent-file-transfer.md)
diff --git a/knowledge/repos/jiuwenswarm/components/extensions-plugins/feature-agentos-sandbox-create-lifecycle.md b/knowledge/repos/jiuwenswarm/components/extensions-plugins/feature-agentos-sandbox-create-lifecycle.md
new file mode 100644
index 00000000..05556ea9
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/extensions-plugins/feature-agentos-sandbox-create-lifecycle.md
@@ -0,0 +1,54 @@
+---
+title: "AgentOS 沙箱创建与幂等对账（jiuwenswarm agentos_router）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/agentos/agentos_router/agent_manager.py:L314-L331, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/agentos/agentos_router/router_client.py:L2480-L2493, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/agentos/agentos_router/config.py:L60-L73, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/agentos/agentos_router/config.py:L344-L357, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/agentos/agentos_router/agent_manager.py:L31-L66, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/agentos/agentos_router/agent_manager.py:L365-L373, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/agentos/agentos_router/agent_manager.py:L592-L598, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/agentos/agentos_router/router_client.py:L2517-L2523, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/agentos/agentos_router/agent_manager.py:L343-L412, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/agentos/agentos_router/agent_manager.py:L536-L553, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/agentos/agentos_router/stale_cleanup.py:L42-L78, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/agentos/agentos_router/stale_cleanup.py:L172-L178, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/agentos/agentos_router/router_client.py:L2319-L2335, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/agentos/agentos_router/router_client.py:L2345-L2350, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/agentos/agentos_router/router_client.py:L2418-L2444]
+feature: "agentos-sandbox-create-lifecycle"
+entry_points: ["jiuwenswarm/extensions/agentos/agentos_router/router_client.py"]
+source_globs: ["jiuwenswarm/extensions/agentos/agentos_router/router_client.py", "jiuwenswarm/extensions/agentos/agentos_router/agent_manager.py", "jiuwenswarm/extensions/agentos/agentos_router/config.py", "jiuwenswarm/extensions/agentos/agentos_router/stale_cleanup.py"]
+---
+
+# AgentOS 沙箱创建与幂等对账（jiuwenswarm agentos_router）
+
+<!-- kb:knowledge owner=feature-agentos-sandbox-create-lifecycle facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**创建与删除入口**
+
+核心入口是 AgentManager.get_or_create_agent(user_id, agent_type, key_values, creator, metadata, acquire)：返回 READY 的 AgentRuntime 快照，或由首个到达者（owner）执行 creator 创建，其余并发请求通过 creating_event 等待；acquire=True 时在锁内递增 task_count 并要求调用方配对 release，保证空闲回收不会在解析与使用之间夺走沙箱。Router 层的 delete_agent(user_id, agent_type, key_values, idle_timeout_seconds) 返回是否删除；带 idle_timeout_seconds 时仅删除 READY 且 task_count==0 且空闲超时的 agent。
+
+Sources / 来源：[jiuwenswarm/extensions/agentos/agentos_router/agent_manager.py:L314–L331](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/agentos/agentos_router/agent_manager.py#L314-L331), [jiuwenswarm/extensions/agentos/agentos_router/router_client.py:L2480–L2493](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/agentos/agentos_router/router_client.py#L2480-L2493)
+
+<!-- kb:knowledge owner=feature-agentos-sandbox-create-lifecycle facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**配置项与环境变量覆盖**
+
+RouterConfig 从 gateway.agentos 段读取：sandbox_idle_timeout_seconds 默认 600（<=0 关闭空闲回收），disconnect_cleanup_timeout_seconds 默认 60，agent_key_fields 默认 (user_id, agent_type)、可选加入 session_id 且前两者必须存在。这两个超时支持环境变量 SANDBOX_IDLE_TIMEOUT_SECONDS / DISCONNECT_CLEANUP_TIMEOUT_SECONDS 覆盖 yaml（显式 0 也生效）；启用 agentos_router 模式还需必填 gateway.agent_client.frontend_endpoint 与 function_version_urn，否则 load_router_config 抛 ValueError。
+
+Sources / 来源：[jiuwenswarm/extensions/agentos/agentos_router/config.py:L60–L73](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/agentos/agentos_router/config.py#L60-L73), [jiuwenswarm/extensions/agentos/agentos_router/config.py:L344–L357](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/agentos/agentos_router/config.py#L344-L357), [jiuwenswarm/extensions/agentos/agentos_router/agent_manager.py:L31–L66](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/agentos/agentos_router/agent_manager.py#L31-L66)
+
+<!-- kb:knowledge owner=feature-agentos-sandbox-create-lifecycle facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**防双创建优先于自动重试**
+
+创建失败后 runtime 被钉为 FAILED，后续请求抛 AgentCreateFailed 而不自动重试——注释明示取舍：已取消/失败的 create 可能已 provision 了 YuanRong 沙箱，重试会造出第二个；只有 AgentPreCreateError（workspace 校验等发生在 YuanRong create 之前的失败）才丢弃 runtime 让下次请求重试，避免瞬时错误被永久缓存。删除路径同样取舍：YuanRong delete_sandbox 失败不阻断内存/注册中心清理，孤儿沙箱按 best-effort 留给手工或后续对账兜底。
+
+Sources / 来源：[jiuwenswarm/extensions/agentos/agentos_router/agent_manager.py:L365–L373](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/agentos/agentos_router/agent_manager.py#L365-L373), [jiuwenswarm/extensions/agentos/agentos_router/agent_manager.py:L592–L598](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/agentos/agentos_router/agent_manager.py#L592-L598), [jiuwenswarm/extensions/agentos/agentos_router/router_client.py:L2517–L2523](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/agentos/agentos_router/router_client.py#L2517-L2523)
+
+<!-- kb:knowledge owner=feature-agentos-sandbox-create-lifecycle facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**单飞创建与启动期对账**
+
+AgentManager.get_or_create_agent 用一把 _runtimes_lock 实现 single-flight：首个到达者成为 owner 执行 creator，后续请求在同一 runtime 的 creating_event 上等待，超时抛 AgentCreatingTimeout、失败抛 AgentCreateFailed。owner 失败默认 mark_failed 钉死 FAILED，但 AgentPreCreateError（发生在 YuanRong create 之前）走 _discard_precreate_failure：移除 runtime 并唤醒等待者重新参与创建，而非缓存失败。启动期 cleanup_stale_sandboxes 列出注册中心全部实例，删除本进程无活跃 runtime 的 YuanRong 沙箱后，以 expected_instance_id 的 CAS 方式注销注册行，避免覆盖并发 upsert 的新实例。
+
+Sources / 来源：[jiuwenswarm/extensions/agentos/agentos_router/agent_manager.py:L343–L412](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/agentos/agentos_router/agent_manager.py#L343-L412), [jiuwenswarm/extensions/agentos/agentos_router/agent_manager.py:L536–L553](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/agentos/agentos_router/agent_manager.py#L536-L553), [jiuwenswarm/extensions/agentos/agentos_router/stale_cleanup.py:L42–L78](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/agentos/agentos_router/stale_cleanup.py#L42-L78), [jiuwenswarm/extensions/agentos/agentos_router/stale_cleanup.py:L172–L178](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/agentos/agentos_router/stale_cleanup.py#L172-L178)
+
+<!-- kb:knowledge owner=feature-agentos-sandbox-create-lifecycle facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**空闲回收与创建超时幂等对账**
+
+空闲回收由后台循环 _idle_reaper_loop 驱动：按 sandbox_idle_check_interval_seconds（默认 30s）周期性执行 _reap_idle_once，后者把 sandbox_idle_timeout_seconds 作为空闲删除阈值传给 delete_agent，因此前者只是检查周期、后者才是回收门槛，二者不可混淆。创建侧的幂等对账：YuanRong create 抛 YuanrongAgentTimeoutError（可能半成功）时，以完全相同的参数重试一次 _create_sandbox_once——沙箱 name 由 user_id+agent_type 确定性派生，首次请求未达则正常新建、已创建则同名幂等复用，不会产生第二个实例；二次仍失败则按原语义上抛（runtime 标 FAILED，防双创建）。
+
+Sources / 来源：[jiuwenswarm/extensions/agentos/agentos_router/router_client.py:L2319–L2335](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/agentos/agentos_router/router_client.py#L2319-L2335), [jiuwenswarm/extensions/agentos/agentos_router/router_client.py:L2345–L2350](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/agentos/agentos_router/router_client.py#L2345-L2350), [jiuwenswarm/extensions/agentos/agentos_router/router_client.py:L2418–L2444](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/agentos/agentos_router/router_client.py#L2418-L2444)
+
diff --git a/knowledge/repos/jiuwenswarm/components/extensions-plugins/feature-applications.md b/knowledge/repos/jiuwenswarm/components/extensions-plugins/feature-applications.md
index 3ee1dbcb..3159aee5 100644
--- a/knowledge/repos/jiuwenswarm/components/extensions-plugins/feature-applications.md
+++ b/knowledge/repos/jiuwenswarm/components/extensions-plugins/feature-applications.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/application-plugins.md
 feature: "applications"
 entry_points: ["jiuwenswarm/extensions/application_host.py"]
-source_globs: ["jiuwenswarm/extensions/application_host.py"]
+source_globs: ["jiuwenswarm/extensions/application_host.py", "jiuwenswarm/channels/web/frontend/src/applicationPlugins/manifest.ts", "jiuwenswarm/channels/web/frontend/src/applicationPlugins/types.ts", "jiuwenswarm/channels/web/frontend/src/applicationPlugins/useApplicationPlugins.ts", "jiuwenswarm/extensions/sdk/application_plugin.py", "jiuwenswarm/channels/web/frontend/src/applicationPlugins/ApplicationTaskControls.tsx", "jiuwenswarm/channels/web/frontend/src/applicationPlugins/taskProgressStore.ts", "jiuwenswarm/channels/web/frontend/src/applicationPlugins/ApplicationPluginOutlet.tsx", "jiuwenswarm/channels/web/frontend/src/App.tsx"]
 ---
 
 # Application Plugin 与前端贡献 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/extensions-plugins/feature-hooks.md b/knowledge/repos/jiuwenswarm/components/extensions-plugins/feature-hooks.md
index 91afdcab..7f4df47b 100644
--- a/knowledge/repos/jiuwenswarm/components/extensions-plugins/feature-hooks.md
+++ b/knowledge/repos/jiuwenswarm/components/extensions-plugins/feature-hooks.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/Harness.md
 feature: "hooks"
 entry_points: ["jiuwenswarm/extensions/manager.py"]
-source_globs: ["jiuwenswarm/extensions/manager.py", "jiuwenswarm/extensions/*.py"]
+source_globs: ["jiuwenswarm/extensions/manager.py", "jiuwenswarm/extensions/*.py", "jiuwenswarm/extensions/callback_compat.py", "jiuwenswarm/extensions/loader.py", "jiuwenswarm/extensions/registry.py", "jiuwenswarm/extensions/sdk/agent_server_client.py", "jiuwenswarm/extensions/sdk/base.py", "jiuwenswarm/extensions/sdk/crypto_utility.py", "jiuwenswarm/extensions/sdk/third_agent.py", "jiuwenswarm/extensions/types.py", "jiuwenswarm/extensions/sdk/__init__.py", "jiuwenswarm/extensions/__init__.py", "jiuwenswarm/gateway/message_handler/message_handler.py", "jiuwenswarm/extensions/hook_event.py", "jiuwenswarm/extensions/hooks_context.py", "jiuwenswarm/gateway/hooks/handler.py", "jiuwenswarm/server/hooks/executor.py", "jiuwenswarm/common/hooks_config.py", "jiuwenswarm/server/runtime/agent_adapter/interface_deep.py", "jiuwenswarm/server/hooks/user_hook_rail.py", "jiuwenswarm/channels/web/frontend/src/App.tsx"]
 ---
 
 # 生命周期 Hooks 与扩展 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/extensions-plugins/feature-video-agent-managed-task-service.md b/knowledge/repos/jiuwenswarm/components/extensions-plugins/feature-video-agent-managed-task-service.md
new file mode 100644
index 00000000..8d687980
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/extensions-plugins/feature-video-agent-managed-task-service.md
@@ -0,0 +1,46 @@
+---
+title: "Voice/Video Duplex Managed Agent Task Service（持久队列、并发与不确定性语义）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/video_duplex/backend/tasks/service.py:L1-L16, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/video_duplex/backend/tasks/service.py:L34-L48, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/video_duplex/backend/tasks/service.py:L183-L236, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/video_duplex/backend/tasks/service.py:L276-L279, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/video_duplex/backend/tasks/service.py:L193-L210, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/video_duplex/backend/tasks/service.py:L211-L235, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/video_duplex/backend/tasks/service.py:L336-L374, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/video_duplex/backend/tasks/service.py:L413-L428, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/video_duplex/tests/backend/test_managed_tasks.py:L172-L194, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/video_duplex/tests/backend/test_managed_tasks.py:L127-L144, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/video_duplex/tests/backend/test_managed_tasks.py:L87-L106, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/video_duplex/tests/backend/test_managed_tasks.py:L241-L267]
+feature: "video-agent-managed-task-service"
+entry_points: ["jiuwenswarm/extensions/video_duplex/backend/tasks/service.py"]
+source_globs: ["jiuwenswarm/extensions/video_duplex/backend/tasks/service.py", "jiuwenswarm/extensions/video_duplex/backend/tasks/rail.py"]
+---
+
+# Voice/Video Duplex Managed Agent Task Service（持久队列、并发与不确定性语义）
+
+<!-- kb:knowledge owner=feature-video-agent-managed-task-service facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**任务服务的公开入口与契约**
+
+`TaskService(store, executor, *, on_change, concurrency, notification_timeout)` 是核心构造入口，围绕一个注入的 Agent 执行器工作，与媒体/RPC 无关（模块 docstring 明示）。公开操作包括 `submit(owner, session, command_id, instruction, request)`、`get`、`list`、`modify`、`cancel`、`answer`、`reorder`、`snapshot`、`preempt` 和 `close`。生命周期上 `submit/get/list` 等都会先调用 `start()`：它通过 `portalocker` 独占租约文件，并把上一个进程遗留的 `running/cancelling/waiting_user` 任务标记为 `unknown`（"Execution ownership lost; tools were not replayed"），不自动重放。错误契约具体且可枚举：`submit` 校验 owner 为字符串、instruction 非空且 ≤16000 字符、`depends_on/resources` 各为 ≤32 个 ≤256 字符的非空字符串，否则 `ValueError`；`modify` 在 revision 不匹配或已有 successor 时抛 `TaskRevisionConflict`，`reorder` 在队列版本变化时抛 `QueueVersionConflict`。
+
+Sources / 来源：[jiuwenswarm/extensions/video_duplex/backend/tasks/service.py:L1–L16](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/video_duplex/backend/tasks/service.py#L1-L16), [jiuwenswarm/extensions/video_duplex/backend/tasks/service.py:L34–L48](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/video_duplex/backend/tasks/service.py#L34-L48), [jiuwenswarm/extensions/video_duplex/backend/tasks/service.py:L183–L236](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/video_duplex/backend/tasks/service.py#L183-L236), [jiuwenswarm/extensions/video_duplex/backend/tasks/service.py:L276–L279](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/video_duplex/backend/tasks/service.py#L276-L279)
+
+<!-- kb:knowledge owner=feature-video-agent-managed-task-service facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**构造参数与请求字段**
+
+构造参数为 `TaskService(store, executor, *, on_change=None, concurrency=2, notification_timeout=2)`：concurrency 必须为正整数否则 `ValueError`，notification_timeout 限定 `on_change` 投递的 `asyncio.wait_for` 超时。任务 request 支持 `independent`（布尔）、`depends_on` 与 `resources`（各 ≤32 项、每项非空 ≤256 字符）；`resources` 在提交时逐项 strip、反斜杠替换为 `/`、casefold 归一并去重，保存为排序列表。
+
+Sources / 来源：[jiuwenswarm/extensions/video_duplex/backend/tasks/service.py:L34–L48](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/video_duplex/backend/tasks/service.py#L34-L48), [jiuwenswarm/extensions/video_duplex/backend/tasks/service.py:L193–L210](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/video_duplex/backend/tasks/service.py#L193-L210)
+
+<!-- kb:knowledge owner=feature-video-agent-managed-task-service facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**幂等回执与取消行为**
+
+`submit` 以 command_id 查询回放记录，命中时返回既有任务并附 `reused: True`；`modify`、`cancel`、`answer` 命中回放时返回已存储的回执，`reorder` 则仅在显式传入 command_id 时才记录/回放。取消语义：`queued` 且无 `resume_answer` 的任务直接置 `cancelled`，其余非终态置 `cancelling` 并返回中文回执（"取消已受理，正在等待执行停止；尚未确认停止。" 等），随后异步调用 `executor.cancel` 并确认 `execution_settled` 后才落 `cancelled`。
+
+Sources / 来源：[jiuwenswarm/extensions/video_duplex/backend/tasks/service.py:L211–L235](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/video_duplex/backend/tasks/service.py#L211-L235), [jiuwenswarm/extensions/video_duplex/backend/tasks/service.py:L336–L374](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/video_duplex/backend/tasks/service.py#L336-L374), [jiuwenswarm/extensions/video_duplex/backend/tasks/service.py:L413–L428](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/video_duplex/backend/tasks/service.py#L413-L428)
+
+<!-- kb:knowledge owner=feature-video-agent-managed-task-service facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**test_managed_tasks.py 覆盖的关键契约**
+
+测试通过可门控的假 Executor 驱动真实 TaskService。test_restart_does_not_replay_dispatched_effect 验证重启接管：close 后重开 store，运行中任务变 unknown、排队任务保持 queued，且重放的 submit 不会再次调用 executor。test_unconfirmed_stop_preserves_uncertainty 验证取消未确认（execution_settled 为假）时任务停在 cancelling、并发位不被释放。test_queued_change_and_order_are_authoritative 验证队列版本的 reorder 冲突与排队中修改注入执行指令；test_running_changes_exact_binding_and_model_observation 与 test_context_write_failure_never_claims_success_or_replays 验证 checkpoint 的修改绑定、context_written/model_input_observed 状态迁移及写失败落 unknown。
+
+Sources / 来源：[jiuwenswarm/extensions/video_duplex/tests/backend/test_managed_tasks.py:L172–L194](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/video_duplex/tests/backend/test_managed_tasks.py#L172-L194), [jiuwenswarm/extensions/video_duplex/tests/backend/test_managed_tasks.py:L127–L144](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/video_duplex/tests/backend/test_managed_tasks.py#L127-L144), [jiuwenswarm/extensions/video_duplex/tests/backend/test_managed_tasks.py:L87–L106](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/video_duplex/tests/backend/test_managed_tasks.py#L87-L106), [jiuwenswarm/extensions/video_duplex/tests/backend/test_managed_tasks.py:L241–L267](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/video_duplex/tests/backend/test_managed_tasks.py#L241-L267)
+
diff --git a/knowledge/repos/jiuwenswarm/components/extensions-plugins/feature-video-duplex.md b/knowledge/repos/jiuwenswarm/components/extensions-plugins/feature-video-duplex.md
index a516c552..bc66e2f1 100644
--- a/knowledge/repos/jiuwenswarm/components/extensions-plugins/feature-video-duplex.md
+++ b/knowledge/repos/jiuwenswarm/components/extensions-plugins/feature-video-duplex.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/application-plugins.md
 feature: "video-duplex"
 entry_points: ["jiuwenswarm/extensions/video_duplex/backend/tasks/rail.py"]
-source_globs: ["jiuwenswarm/extensions/video_duplex/backend/tasks/rail.py", "jiuwenswarm/extensions/video_duplex/*"]
+source_globs: ["jiuwenswarm/extensions/video_duplex/backend/tasks/rail.py", "jiuwenswarm/extensions/video_duplex/*", "jiuwenswarm/extensions/video_duplex/backend/video_search.py", "jiuwenswarm/extensions/video_duplex/frontend/VideoLivePanel/index.tsx", "jiuwenswarm/extensions/video_duplex/backend/video_live.py", "jiuwenswarm/extensions/video_duplex/frontend/VideoLivePanel/joyaiPromptLifecycle.ts", "jiuwenswarm/extensions/video_duplex/frontend/VideoLivePanel/joyaiProvider.ts", "jiuwenswarm/extensions/video_duplex/frontend/VideoLivePanel/joyaiToolContext.ts", "jiuwenswarm/extensions/video_duplex/frontend/VideoLivePanel/joyaiVoice.ts", "jiuwenswarm/extensions/video_duplex/backend/joyai_provider.py", "jiuwenswarm/extensions/video_duplex/frontend/VideoLivePanel/qwenOmniProtocol.ts", "jiuwenswarm/extensions/video_duplex/frontend/VideoLivePanel/qwenOmniSession.ts", "jiuwenswarm/extensions/video_duplex/frontend/VideoLivePanel/qwenOmniTools.ts", "jiuwenswarm/extensions/video_duplex/frontend/VideoLivePanel/videoSource.ts", "jiuwenswarm/extensions/video_duplex/frontend/VideoLivePanel/searchPresentation.ts", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/experimental/ExperimentalSettings.tsx", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/experimental/VideoDuplexModelSettings.tsx", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/experimental/definition.ts", "jiuwenswarm/extensions/video_duplex/frontend/index.tsx", "jiuwenswarm/extensions/video_duplex/frontend/VideoLivePanel/types.ts", "jiuwenswarm/extensions/video_duplex/backend/video_files.py", "jiuwenswarm/extensions/video_duplex/backend/tasks/server_adapter.py", "jiuwenswarm/extensions/video_duplex/backend/tasks/store.py", "jiuwenswarm/extensions/video_duplex/frontend/VideoLivePanel/replyLanguage.ts", "jiuwenswarm/extensions/video_duplex/frontend/VideoLivePanel/taskPrompts.ts"]
 ---
 
 # 音视频双工扩展 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/extensions-plugins/feature-yuanrong-agent-file-transfer.md b/knowledge/repos/jiuwenswarm/components/extensions-plugins/feature-yuanrong-agent-file-transfer.md
new file mode 100644
index 00000000..38ef5466
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/extensions-plugins/feature-yuanrong-agent-file-transfer.md
@@ -0,0 +1,30 @@
+---
+title: "YuanRong Agent 容器文件传输（上传/下载/列举/建目录）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/yuanrong_frontend_client.py:L804-L812, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/web/container_file_http.py:L469-L479, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/web/container_file_http.py:L489-L549, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/web/container_file_http.py:L698-L743, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/yuanrong_frontend_client.py:L1027-L1041, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/yuanrong_frontend_client.py:L895-L903, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/web/container_file_http.py:L55-L67, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/web/container_file_http.py:L563-L565]
+feature: "yuanrong-agent-file-transfer"
+entry_points: ["jiuwenswarm/extensions/yuanrong_frontend_client.py"]
+source_globs: ["jiuwenswarm/extensions/yuanrong_frontend_client.py", "jiuwenswarm/gateway/channel_manager/web/container_file_http.py"]
+---
+
+# YuanRong Agent 容器文件传输（上传/下载/列举/建目录）
+
+<!-- kb:knowledge owner=feature-yuanrong-agent-file-transfer facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**两层结构：YuanRong 前端客户端与网关 HTTP 路由**
+
+下层是 `YuanRongFrontendAgentClient`：同步 HTTP 通过 `asyncio.to_thread` 包成异步，统一经 `bind_southbound_trace_id` 绑定 trace，错误集中在 `_agent_file_http_error` 分类抛 `YuanrongAgentFileError`。上层是 WebChannel 的 `/file-api` 路由（`attach_container_file_routes`）：仅当 `channel.container_file_client` 是 `AgentOSRouterClient` 时挂载，各路由把请求转成 `client.upload/download/list_container_files`、`mkdir_container_dir` 调用。路由前置一个 HTTP 中间件调用 `client.authenticate_http` 做鉴权并把 IAM 身份写入 request.state。下载 `/file-api/download` 有两条分支：`verified_asset_v1` token 经 `fetch_agent_unary` 向 AgentServer 取验证分块；否则从 token 解出 path/session 后走 `download_container_file` 以 64KiB 分块流式输出。所示片段未包含 AgentOSRouterClient 实现，其调用是否落到上述 YuanRong files 接口无法在本次证据内确认。
+
+Sources / 来源：[jiuwenswarm/extensions/yuanrong_frontend_client.py:L804–L812](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/yuanrong_frontend_client.py#L804-L812), [jiuwenswarm/gateway/channel_manager/web/container_file_http.py:L469–L479](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/web/container_file_http.py#L469-L479), [jiuwenswarm/gateway/channel_manager/web/container_file_http.py:L489–L549](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/web/container_file_http.py#L489-L549), [jiuwenswarm/gateway/channel_manager/web/container_file_http.py:L698–L743](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/web/container_file_http.py#L698-L743)
+
+<!-- kb:knowledge owner=feature-yuanrong-agent-file-transfer facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**关键参数：mode、max_depth 与轮询超时**
+
+`mkdir` 的 `mode` 是可选的：None 或空白字符串归一化为 None（由调用方 umask 决定），仅当给出时才要求匹配 3-4 位八进制数字（如 755 或 0700），否则抛 `YuanrongAgentFileError(BAD_REQUEST)`；网关 `/file-api/mkdir` 同样接受可空的 `mode` 查询参数。`max_depth` 只出现在列举链路（客户端 `list_agent_files` 和网关 `ListFilesQuery`/`_list_container_dir`），mkdir 无此参数；负值处理不对称——客户端抛 `ValueError`（yuanrong_frontend_client.py:902-903），网关返回 HTTP 400（container_file_http.py:564-565）。另外 `wait_until_running` 的超时与重试间隔可由实例属性覆盖，否则用模块常量 `_AGENT_RUNNING_TIMEOUT_SECONDS` / `_AGENT_RUNNING_RETRY_INTERVAL_SECONDS`。
+
+Sources / 来源：[jiuwenswarm/extensions/yuanrong_frontend_client.py:L1027–L1041](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/yuanrong_frontend_client.py#L1027-L1041), [jiuwenswarm/extensions/yuanrong_frontend_client.py:L895–L903](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/yuanrong_frontend_client.py#L895-L903), [jiuwenswarm/gateway/channel_manager/web/container_file_http.py:L55–L67](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/web/container_file_http.py#L55-L67), [jiuwenswarm/gateway/channel_manager/web/container_file_http.py:L563–L565](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/web/container_file_http.py#L563-L565)
+
diff --git a/knowledge/repos/jiuwenswarm/components/extensions-plugins/feature-yuanrong-faas-invocation.md b/knowledge/repos/jiuwenswarm/components/extensions-plugins/feature-yuanrong-faas-invocation.md
new file mode 100644
index 00000000..a25514f0
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/extensions-plugins/feature-yuanrong-faas-invocation.md
@@ -0,0 +1,48 @@
+---
+title: "YuanRong FaaS 函数调用（非流式 + SSE 流式）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/yuanrong_frontend_client.py:L1549-L1562, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/yuanrong_frontend_client.py:L1945-L1975, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/clawee.py:L105-L117, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/clawee.py:L233-L276, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/agent_client/extension.py:L31-L57, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/yuanrong_frontend_client.py:L1748-L1787, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/yuanrong_frontend_client.py:L1553-L1562, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/yuanrong_frontend_client.py:L1579-L1612, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/yuanrong_frontend_client.py:L1650-L1695, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/clawee.py:L233-L299, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/clawee.py:L226-L240, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/clawee.py:L309-L316, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/yuanrong_frontend_client.py:L1862-L1876, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/yuanrong_frontend_client.py:L1963-L1975]
+feature: "yuanrong-faas-invocation"
+entry_points: ["jiuwenswarm/extensions/yuanrong_frontend_client.py"]
+source_globs: ["jiuwenswarm/extensions/yuanrong_frontend_client.py", "jiuwenswarm/extensions/clawee.py", "jiuwenswarm/extensions/agent_client/extension.py"]
+---
+
+# YuanRong FaaS 函数调用（非流式 + SSE 流式）
+
+<!-- kb:knowledge owner=feature-yuanrong-faas-invocation facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**HTTP invoke 与 FakeWs 适配的双端结构**
+
+客户端把 E2AEnvelope `to_dict()` 直接作为 POST body 发往 `{frontend_endpoint}/serverless/v1/functions/{urn}/invocations`，仅覆盖 `is_stream` 区分流式/非流式，透传完整 channel_context。流式路径在后台线程读 SSE（按行解析 `data: ` 前缀，识别 `[DONE]`），经 `loop.call_soon_threadsafe` 写入 asyncio.Queue 供事件循环消费。服务端 clawee 用 `FakeWs`（仅实现 `send()` 收帧进队列）适配 `AgentWebSocketServer._handle_message`，使 faas 链路与 websocket 链路复用完全相同的处理代码：非流式取最后一帧解析为 unary 响应，流式并发跑 handler 与帧转发、逐帧写 `context.get_stream()`。clawee 还维护长生命周期事件循环避免跨循环绑定问题。
+
+Sources / 来源：[jiuwenswarm/extensions/yuanrong_frontend_client.py:L1549–L1562](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/yuanrong_frontend_client.py#L1549-L1562), [jiuwenswarm/extensions/yuanrong_frontend_client.py:L1945–L1975](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/yuanrong_frontend_client.py#L1945-L1975), [jiuwenswarm/extensions/clawee.py:L105–L117](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/clawee.py#L105-L117), [jiuwenswarm/extensions/clawee.py:L233–L276](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/clawee.py#L233-L276)
+
+<!-- kb:knowledge owner=feature-yuanrong-faas-invocation facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**gateway.agent_client 配置项与默认值**
+
+注册由 `gateway.agent_client.type` 控制：非 "yuanrong"（默认 "websocket"）不注册；yuanrong 模式要求 `frontend_endpoint` 与 `function_version_urn` 非空，否则抛 ValueError。客户端参数及默认值：`concurrency`=1、`invoke_timeout_s`=60.0、`agent_timeout_s`=300.0、`agent_namespace`="default"。请求头方面，`X-Instance-Session` 携带 sessionID/sessionTTL/concurrency；当 user_id 去除首尾空白后非空时附加 `X-Session-Context: {"sessionCtx": <uid>}`，否则仅记一条 logger.info（非 warning 级别）日志且不加该 header——空白字符构成的 user_id 也会被省略该 header。
+
+Sources / 来源：[jiuwenswarm/extensions/agent_client/extension.py:L31–L57](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/agent_client/extension.py#L31-L57), [jiuwenswarm/extensions/yuanrong_frontend_client.py:L1748–L1787](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/yuanrong_frontend_client.py#L1748-L1787)
+
+<!-- kb:knowledge owner=feature-yuanrong-faas-invocation facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**调用行为与 faas 封装处理**
+
+非流式与流式共用 `_build_invoke_payload`：以 `envelope.to_dict()` 透传（含 channel_context），仅覆盖 `is_stream`；流式额外设置 `Accept: text/event-stream`，服务端 clawee 按 `is_stream` 分流：非流式取最后一帧经 `parse_agent_server_wire_unary` 返回，流式逐帧写 `context.get_stream()`。faas executor 的外层 `{"body", "innerCode"}` 封装（需含 body+innerCode 且非标准 AgentResponse 形状）由 `_normalize_faas_body` 剥离并二次解析，body 常是内层 JSON 字符串。`innerCode != "0"` 时错误码写入内层 dict 的 `_faas_error_code` 键；仅非流式解析的前两个分支（wire 解析成功或标准形状）把它复制进 metadata，最终兜底分支省略它，流式 chunk 则丢弃返回的错误码、只拷贝 chunk.metadata。
+
+Sources / 来源：[jiuwenswarm/extensions/yuanrong_frontend_client.py:L1553–L1562](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/yuanrong_frontend_client.py#L1553-L1562), [jiuwenswarm/extensions/yuanrong_frontend_client.py:L1579–L1612](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/yuanrong_frontend_client.py#L1579-L1612), [jiuwenswarm/extensions/yuanrong_frontend_client.py:L1650–L1695](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/yuanrong_frontend_client.py#L1650-L1695), [jiuwenswarm/extensions/clawee.py:L233–L299](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/clawee.py#L233-L299)
+
+<!-- kb:knowledge owner=feature-yuanrong-faas-invocation facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**线程桥接与共享槽位的取舍**
+
+Inference / 设计推断（非作者历史意图）：
+
+复用 `AgentWebSocketServer._handle_message`（经 FakeWs 适配）让 faas 链路走同一处理入口（推断意图：减少双链路行为分叉；注释引用 docs/yuanrong.md 对齐方案），代价是直接依赖服务端私有属性 `_current_ws`/`_current_send_lock`。这些共享槽位在 finally 中被置 None 并清理 ACP capabilities（按 id(ws) 防 FakeWs 泄漏），但没有恢复调用前的上下文，也未对并发调用做隔离或串行化——并发 invoke 之间对这些共享槽位存在竞态风险。客户端侧则用后台线程读 SSE、经 `loop.call_soon_threadsafe` 写入 asyncio.Queue 做线程到事件循环的桥接，行缓冲保留不完整的最后一行以容忍分片。
+
+Sources / 来源：[jiuwenswarm/extensions/clawee.py:L226–L240](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/clawee.py#L226-L240), [jiuwenswarm/extensions/clawee.py:L309–L316](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/clawee.py#L309-L316), [jiuwenswarm/extensions/yuanrong_frontend_client.py:L1862–L1876](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/yuanrong_frontend_client.py#L1862-L1876), [jiuwenswarm/extensions/yuanrong_frontend_client.py:L1963–L1975](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/yuanrong_frontend_client.py#L1963-L1975)
+
diff --git a/knowledge/repos/jiuwenswarm/components/extensions-plugins/knowledge.md b/knowledge/repos/jiuwenswarm/components/extensions-plugins/knowledge.md
new file mode 100644
index 00000000..b94a7766
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/extensions-plugins/knowledge.md
@@ -0,0 +1,27 @@
+---
+title: "jiuwenswarm 扩展与插件：video_duplex 实时音视频 RPC 与 AgentOS Router 客户端"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/application-plugins.md:L57-L62, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/application-plugins.md:L145-L149, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/video_duplex/backend/video_live.py:L692-L698, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/video_duplex/backend/video_live.py:L170-L187, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/video_duplex/backend/video_live.py:L210-L250]
+---
+
+# jiuwenswarm 扩展与插件：video_duplex 实时音视频 RPC 与 AgentOS Router 客户端
+
+<!-- kb:knowledge owner=extensions-plugins facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证入口**
+
+上游文档说明内置 `jiuwenswarm/extensions/video_duplex` 是应用插件的完整参考示例，其配置与测试保留在插件目录内；插件发现与静态资源可用通用 HTTP 接口 `GET /api/application-plugins` 与 `GET /api/application-plugins/{plugin_id}/assets/{asset_path}` 检查。注册成功本身也会写一条 `video_handlers_registered` 事件日志，可作为装配发生的运行时信号。本页展示的输入未包含这些测试文件本身，故不描述其覆盖范围。
+
+Sources / 来源：[docs/zh/application-plugins.md:L57–L62](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/docs/zh/application-plugins.md#L57-L62), [docs/zh/application-plugins.md:L145–L149](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/docs/zh/application-plugins.md#L145-L149), [jiuwenswarm/extensions/video_duplex/backend/video_live.py:L692–L698](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/video_duplex/backend/video_live.py#L692-L698)
+
+<!-- kb:knowledge owner=extensions-plugins facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**环境变量开关与双 Provider 配置**
+
+运行模式由 `VIDEO_LIVE_MODE` 决定：缺省 `joyai`，仅当值（大小写不敏感）为 `realtime` 时切换到 Qwen Omni 实时模式。`VIDEO_DUPLEX_ENABLED` 缺省视为启用，取值 `0/false/no/off` 时禁用。JoyAI 模式下 `_realtime_config` 读取 `joyai_provider.model_config()`，任一为空即以 `VIDEO_CONFIG_ERROR` 返回错误信息“请配置 JOYAI_API_BASE 和 JOYAI_MODEL_NAME”（具体读取逻辑在未提供的 joyai_provider 中）；realtime 模式则由 `QwenOmniRealtimeConfig.from_environment()` 构造并 `validate()`，仅 `validate()` 抛出的 ValueError 被转为 `VIDEO_CONFIG_ERROR`，`from_environment()` 本身在 try 块之外。
+
+Sources / 来源：[jiuwenswarm/extensions/video_duplex/backend/video_live.py:L170–L187](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/video_duplex/backend/video_live.py#L170-L187), [jiuwenswarm/extensions/video_duplex/backend/video_live.py:L210–L250](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/video_duplex/backend/video_live.py#L210-L250)
+
diff --git a/knowledge/repos/jiuwenswarm/components/gateway-channels/_index.md b/knowledge/repos/jiuwenswarm/components/gateway-channels/_index.md
index 8d9b69b7..46188ddd 100644
--- a/knowledge/repos/jiuwenswarm/components/gateway-channels/_index.md
+++ b/knowledge/repos/jiuwenswarm/components/gateway-channels/_index.md
@@ -21,7 +21,8 @@ sources: []
 
 | PR 描述在做什么 | 精确规则 | 第一批 live 源码 |
 |---|---|---|
-| cli、chat、命令行、CLI 频道、gateway client、websocket、tui、renderer、jsonl、spinner、SIGINT、… | 入口 | `jiuwenswarm/channels/cli/`、`jiuwenswarm/channels/process_cli/` |
+| cli、chat、命令行、CLI 频道、gateway client、websocket、tui、renderer、jsonl、spinner、SIGINT、… | 入口 | `jiuwenswarm/channels/`、`jiuwenswarm/channels/cli/`、`jiuwenswarm/channels/process_cli/` |
+
 
 - [Process CLI 频道（jiuwenswarm/channels/process_cli）审查规则](rules.md)
 
@@ -65,3 +66,15 @@ sources: []
 - [Telegram 频道：实现深读](feature-depth-im-telegram.md)
 - [Discord 频道：实现深读](feature-depth-im-discord.md)
 - [WhatsApp 频道：实现深读](feature-depth-im-whatsapp.md)
+- [Gateway Web 频道处理器（channel_manager/web/app_web_handlers.py）](knowledge-gateway-channels.md)
+- [进程式 CLI 频道（process_cli）：REPL、worker 与会话操作](knowledge.md)
+- [/security-review 安全审查斜杠命令与 git 预执行](feature-channel-security-review-slash-command.md)
+- [Gateway Config-Save Hot Reload（_on_config_saved：agent.reload_config 重试、重启兜底与副作用）](feature-gateway-config-hot-reload.md)
+- [Gateway HealthCheck 周期探活服务 (jiuwenswarm/gateway/health_check)](feature-gateway-health-check.md)
+- [GatewayServer 多路由 WebSocket 宿主与会话/请求路由表](feature-gateway-server-multi-route-ws.md)
+- [IM Attachment Persist Hook (E2A + HTTP Bridge) — ChannelManager wiring](feature-im-attachment-persist-hook-969909e1.md)
+- [IM Channel Hot Reconfiguration (_apply_channel_config lifecycle across 11 channels)](feature-im-channel-hot-reconfig.md)
+- [界面语言配置 RPC（preferred_language）— Gateway Web Handler](feature-locale-conf-rpc.md)
+- [3rdagent.list / 3rdagent.switch 第三方智能体切换](feature-thirdagent-list-switch.md)
+- [@path 文件引用内联与 @agent 提及解析（MessageHandler）](feature-at-file-reference-inlining-b1a822e1.md)
+- [scripts](scripts/_index.md)
diff --git a/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-at-file-reference-inlining-b1a822e1.md b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-at-file-reference-inlining-b1a822e1.md
new file mode 100644
index 00000000..2ebd03c4
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-at-file-reference-inlining-b1a822e1.md
@@ -0,0 +1,56 @@
+---
+title: "@path 文件引用内联与 @agent 提及解析（MessageHandler）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/message_handler/message_handler.py:L2873-L2915, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/message_handler/message_handler.py:L2917-L2944, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/message_handler/message_handler.py:L2882-L2889, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/message_handler/message_handler.py:L2950-L2987, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/message_handler/message_handler.py:L3007-L3039, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/message_handler/message_handler.py:L2878-L2913, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/message_handler/message_handler.py:L2928-L2935, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/message_handler/message_handler.py:L2891-L2913, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:tests/unit_tests/gateway/test_agent_mentions.py:L75-L77, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/message_handler/message_handler.py:L2917-L2924]
+feature: "at-file-reference-inlining-b1a822e1"
+entry_points: ["jiuwenswarm/gateway/message_handler/message_handler.py"]
+source_globs: ["jiuwenswarm/gateway/message_handler/message_handler.py"]
+---
+
+# @path 文件引用内联与 @agent 提及解析（MessageHandler）
+
+<!-- kb:knowledge owner=feature-at-file-reference-inlining-b1a822e1 facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**公开入口与行为契约**
+
+`MessageHandler.resolve_at_file_references(content, ...)` 通过正则替换把 `@path` 引用替换为 `<file-content path="...">` 块；非文件路径、`@agent-`/`@agent:` 前缀及读取异常（OSError、UnicodeDecodeError）时原样保留匹配文本。`extract_agent_mentions(content)` 是静态方法，解析 `@"<type> (agent)"` 与 `@agent-<type>` 两种格式，返回去掉 `agent-` 前缀的类型名并去重——注意其保序是“按格式分组”的顺序：先收集全部引号格式再收集全部非引号格式（如 `@agent-a @"b (agent)"` 返回 `["b", "a"]`），并非消息中的出现顺序。
+
+Sources / 来源：[jiuwenswarm/gateway/message_handler/message_handler.py:L2873–L2915](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/message_handler/message_handler.py#L2873-L2915), [jiuwenswarm/gateway/message_handler/message_handler.py:L2917–L2944](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/message_handler/message_handler.py#L2917-L2944)
+
+<!-- kb:knowledge owner=feature-at-file-reference-inlining-b1a822e1 facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**解析流程与路径解析的分布**
+
+附件流程为：`_resolve_structured_attachments` 调用 `_normalize_structured_attachments`（解析路径、按已解析路径去重、补全 type 默认 `file` 与 filename），再把附件拼成 `@"path"` 前缀、经 `strip_attached_mentions` 清理后调用 `resolve_at_file_references` 内联。路径解析逻辑存在两份并行实现：`_resolve_reference_path`（L2951–L2957，供附件与 strip 使用）与 `resolve_at_file_references` 内部 `_replacer` 中的相同 `~/`/绝对/相对规则（L2883–L2889），并非集中一处。`strip_attached_mentions` 的正则支持引号/裸路径及可选 `#suffix`，仅当解析路径命中附件集合时才把 `@` 锚点剥掉，否则整段原样保留（L3018–L3021）。
+
+Sources / 来源：[jiuwenswarm/gateway/message_handler/message_handler.py:L2882–L2889](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/message_handler/message_handler.py#L2882-L2889), [jiuwenswarm/gateway/message_handler/message_handler.py:L2950–L2987](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/message_handler/message_handler.py#L2950-L2987), [jiuwenswarm/gateway/message_handler/message_handler.py:L3007–L3039](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/message_handler/message_handler.py#L3007-L3039)
+
+<!-- kb:knowledge owner=feature-at-file-reference-inlining-b1a822e1 facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的语法与依赖**
+
+文件引用内联跳过 `agent-`/`agent:` 前缀的裸引用，将存在的文件内容包进 `<file-content path="原始引用">` 块，截断时附 `... (truncated, original_size=N bytes)` 后缀；读取用 `errors="replace"` 容忍非 UTF-8 字节。agent 提及支持 `@"<type> (agent)"`（引号格式）与 `@agent-<type>`（裸格式），类型名字符类为 `[\w:.@-]+`，返回去重列表（保序按格式分组顺序）。
+
+Sources / 来源：[jiuwenswarm/gateway/message_handler/message_handler.py:L2878–L2913](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/message_handler/message_handler.py#L2878-L2913), [jiuwenswarm/gateway/message_handler/message_handler.py:L2928–L2935](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/message_handler/message_handler.py#L2928-L2935)
+
+<!-- kb:knowledge owner=feature-at-file-reference-inlining-b1a822e1 facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**取舍与限制**
+
+Inference / 设计推断（非作者历史意图）：
+
+引用解析采取“静默降级”策略：路径不存在、OSError 或 UnicodeDecodeError 都原样返回匹配文本（L2893–L2894、L2912–L2913），调用方无法从返回值区分“非文件引用”与“读取失败”；且因 `errors="replace"`（L2898、L2900），实际到达 except 的 UnicodeDecodeError 很少触发，坏字节被替换字符吞掉而非保留原文。截断按字符切片而非字节（L2904–L2905），换取实现简单但限制不严格。无意图方面的文档证据，此分析为基于代码的推断。
+
+Sources / 来源：[jiuwenswarm/gateway/message_handler/message_handler.py:L2891–L2913](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/message_handler/message_handler.py#L2891-L2913)
+
+<!-- kb:knowledge owner=feature-at-file-reference-inlining-b1a822e1 facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**现有测试入口**
+
+`tests/unit_tests/gateway/test_agent_mentions.py` 直接针对该特性，其中 `test_empty` 调用 `MessageHandler.extract_agent_mentions("no mentions here")` 并断言返回空列表，验证无提及时的安全返回（该方法对空/无匹配内容返回 `[]`，见 L2923–L2924）。该文件共 88 行，覆盖 `extract_agent_mentions` 的解析行为；但所示片段未包含针对 `resolve_at_file_references`、截断或附件合并路径的测试，这些行为在所示输入中的验证情况未知。
+
+Sources / 来源：[tests/unit_tests/gateway/test_agent_mentions.py:L75–L77](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/tests/unit_tests/gateway/test_agent_mentions.py#L75-L77), [jiuwenswarm/gateway/message_handler/message_handler.py:L2917–L2924](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/message_handler/message_handler.py#L2917-L2924)
+
diff --git a/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-channel-security-review-slash-command.md b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-channel-security-review-slash-command.md
new file mode 100644
index 00000000..3d9324f1
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-channel-security-review-slash-command.md
@@ -0,0 +1,64 @@
+---
+title: "/security-review 安全审查斜杠命令与 git 预执行"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/message_handler/message_handler.py:L4740-L4771, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/message_handler/prompts/security_review_prompt.py:L243-L263, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/message_handler/prompts/security_review_prompt.py:L18-L36, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/message_handler/prompts/security_review_prompt.py:L253-L263, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/message_handler/message_handler.py:L4741-L4746, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/message_handler/prompts/security_review_prompt.py:L14-L23, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/message_handler/prompts/security_review_prompt.py:L48-L60, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/message_handler/message_handler.py:L4732-L4739, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/message_handler/message_handler.py:L4747-L4758, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/message_handler/prompts/security_review_prompt.py:L14-L22, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/message_handler/prompts/security_review_prompt.py:L26-L45, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/message_handler/message_handler.py:L4759-L4766, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/message_handler/prompts/security_review_prompt.py:L48-L51]
+feature: "channel-security-review-slash-command"
+entry_points: ["jiuwenswarm/gateway/message_handler/message_handler.py", "jiuwenswarm/gateway/message_handler/prompts/security_review_prompt.py"]
+source_globs: ["jiuwenswarm/gateway/message_handler/message_handler.py", "jiuwenswarm/gateway/message_handler/prompts/security_review_prompt.py"]
+---
+
+# /security-review 安全审查斜杠命令与 git 预执行
+
+<!-- kb:knowledge owner=feature-channel-security-review-slash-command facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**入口与函数契约**
+
+命令在网关消息处理循环中被识别（ParsedControlAction.SECURITY_REVIEW_OK），取解析出的附加参数与消息 metadata 里的 cwd，调用 `build_security_review_prompt(extra_arg, cwd)` 生成 prompt，替换 msg.params 的 query/content 后继续转发。`build_security_review_prompt` 是公开构建函数：cwd 非 None 时预执行 4 条只读 git 命令并内联输出；任一非零退出抛 `GitPreExecError`，调用方捕获后通过 send_channel_notice 告知用户并 `continue` 中止转发。
+
+Sources / 来源：[jiuwenswarm/gateway/message_handler/message_handler.py:L4740–L4771](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/message_handler/message_handler.py#L4740-L4771), [jiuwenswarm/gateway/message_handler/prompts/security_review_prompt.py:L243–L263](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/message_handler/prompts/security_review_prompt.py#L243-L263)
+
+<!-- kb:knowledge owner=feature-channel-security-review-slash-command facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**可配置项与来源**
+
+该功能本身几乎没有用户可配置项：输出语言来自全局 config 的 `preferred_language`（经 `response_language_line()` 注入）；git 上下文目录取自消息 metadata 的 `cwd` 字段（非 dict 时为 None）。diff/log 基线固定为 `origin/HEAD...`，命令清单硬编码在 `_SECURITY_REVIEW_GIT_COMMANDS`，每条超时 30 秒。用户唯一输入是斜杠命令后的附加参数，去掉首尾空白后原样作为 "Additional instructions" 透传。
+
+Sources / 来源：[jiuwenswarm/gateway/message_handler/prompts/security_review_prompt.py:L18–L36](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/message_handler/prompts/security_review_prompt.py#L18-L36), [jiuwenswarm/gateway/message_handler/prompts/security_review_prompt.py:L253–L263](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/message_handler/prompts/security_review_prompt.py#L253-L263), [jiuwenswarm/gateway/message_handler/message_handler.py:L4741–L4746](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/message_handler/message_handler.py#L4741-L4746)
+
+<!-- kb:knowledge owner=feature-channel-security-review-slash-command facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的行为**
+
+功能是安全审查 prompt 的确定性构建：cwd 存在时预执行 `git status`、`git diff --name-only origin/HEAD...`、`git log --no-decorate origin/HEAD...`、`git diff origin/HEAD...` 四条只读命令，输出按固定标签内联进 prompt，LLM 无需自行跑 git；cwd 为 None（如单测、无仓库上下文）时回退到旧的指令式 prompt，行为不变。参数校验前置：参数过长或含非法控制字符时发 notice 拒绝。prompt 正文要求只报高置信度漏洞，附排除清单与输出格式。
+
+Sources / 来源：[jiuwenswarm/gateway/message_handler/prompts/security_review_prompt.py:L14–L23](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/message_handler/prompts/security_review_prompt.py#L14-L23), [jiuwenswarm/gateway/message_handler/prompts/security_review_prompt.py:L48–L60](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/message_handler/prompts/security_review_prompt.py#L48-L60), [jiuwenswarm/gateway/message_handler/message_handler.py:L4732–L4739](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/message_handler/message_handler.py#L4732-L4739)
+
+<!-- kb:knowledge owner=feature-channel-security-review-slash-command facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**设计取舍**
+
+Inference / 设计推断（非作者历史意图）：
+
+预执行 + 内联的收益是把上下文获取变成确定性的：LLM 不再自行跑 git，失败语义明确（注释说明 git 语义下 exit!=0 才是真失败，有 diff 时 exit 0）。代价是同步 subprocess 开销（注释提及 4×30s 最坏情况），用 executor 缓解但仍占用线程；基线硬编码 `origin/HEAD...`，在 origin/HEAD 未设置或无共同历史的仓库会直接中止整个命令。回退路径保留旧行为是兼容性取舍。
+
+Sources / 来源：[jiuwenswarm/gateway/message_handler/message_handler.py:L4747–L4758](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/message_handler/message_handler.py#L4747-L4758), [jiuwenswarm/gateway/message_handler/prompts/security_review_prompt.py:L14–L22](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/message_handler/prompts/security_review_prompt.py#L14-L22)
+
+<!-- kb:knowledge owner=feature-channel-security-review-slash-command facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**控制流与数据流**
+
+消息处理循环识别出 ParsedControlAction.SECURITY_REVIEW_OK 后，从消息 metadata 取 cwd（非 dict 时为 None），经 `run_in_executor` 调用 `build_security_review_prompt(extra_arg, cwd)`，把返回的 prompt 覆盖写入 msg.params 的 query/content 后继续向 Agent 转发。prompt 构建分两条路径：cwd 非 None 时在 `_run_security_review_git` 中同步预执行 4 条只读 git 命令（每条 timeout=30s）并内联输出；cwd 为 None 时退回指令式 fallback prompt，让 LLM 自行跑 git，不触发任何子进程。异常处理只针对 `GitPreExecError`（git 非零退出）：捕获后 send_channel_notice 告知用户并 `continue` 中止转发；`subprocess.run` 自身抛出的其他异常（如超时）不在该 except 范围内，所示代码未体现其处理方式。
+
+Sources / 来源：[jiuwenswarm/gateway/message_handler/message_handler.py:L4740–L4771](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/message_handler/message_handler.py#L4740-L4771), [jiuwenswarm/gateway/message_handler/prompts/security_review_prompt.py:L243–L263](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/message_handler/prompts/security_review_prompt.py#L243-L263), [jiuwenswarm/gateway/message_handler/prompts/security_review_prompt.py:L26–L45](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/message_handler/prompts/security_review_prompt.py#L26-L45)
+
+<!-- kb:knowledge owner=feature-channel-security-review-slash-command facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**可观察的校验行为**
+
+所示片段中该功能的校验发生在两处命令前置检查与 git 预执行：参数过长或含非法控制字符时（SECURITY_REVIEW_OK 之前的分支）发 notice 拒绝该消息；cwd 非 None 时任一 git 命令非零退出抛 `GitPreExecError`，由消息处理器转为 notice 并中止。源码注释以「如单测」举例说明 cwd=None 的 fallback 路径，但这只是举例措辞，所示输入未包含任何测试文件，不能据此断言实际存在的测试入口或其覆盖范围。
+
+Sources / 来源：[jiuwenswarm/gateway/message_handler/message_handler.py:L4732–L4739](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/message_handler/message_handler.py#L4732-L4739), [jiuwenswarm/gateway/message_handler/message_handler.py:L4759–L4766](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/message_handler/message_handler.py#L4759-L4766), [jiuwenswarm/gateway/message_handler/prompts/security_review_prompt.py:L48–L51](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/message_handler/prompts/security_review_prompt.py#L48-L51)
+
diff --git a/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-cli.md b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-cli.md
index 0135e1a4..522f187f 100644
--- a/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-cli.md
+++ b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-cli.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/命令行指令.md
 feature: "cli"
 entry_points: ["jiuwenswarm/cli/main.py"]
-source_globs: ["jiuwenswarm/cli/main.py", "jiuwenswarm/cli/*.py"]
+source_globs: ["jiuwenswarm/cli/main.py", "jiuwenswarm/cli/*.py", "jiuwenswarm/channels/cli/chat.py", "jiuwenswarm/channels/cli/main.py", "jiuwenswarm/cli/_terminal.py", "jiuwenswarm/cli/chat.py", "jiuwenswarm/cli/gateway_client.py", "jiuwenswarm/channels/cli/events.py", "jiuwenswarm/channels/cli/gateway_client.py", "jiuwenswarm/gateway/message_handler/prompts/__init__.py", "jiuwenswarm/gateway/message_handler/prompts/review_prompt.py"]
 ---
 
 # 交互式命令行 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-gateway-config-hot-reload.md b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-gateway-config-hot-reload.md
new file mode 100644
index 00000000..9eced16f
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-gateway-config-hot-reload.md
@@ -0,0 +1,54 @@
+---
+title: "Gateway Config-Save Hot Reload（_on_config_saved：agent.reload_config 重试、重启兜底与副作用）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/app_gateway.py:L2065-L2072, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/app_gateway.py:L2113-L2124, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/app_gateway.py:L2032-L2086, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/app_gateway.py:L2119-L2125, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/app_gateway.py:L2057-L2058, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/app_gateway.py:L2090-L2135, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/app_gateway.py:L2039-L2058, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/app_gateway.py:L2137-L2159, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/app_gateway.py:L2080-L2084, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/app_gateway.py:L2102-L2125]
+feature: "gateway-config-hot-reload"
+entry_points: ["jiuwenswarm/gateway/app_gateway.py"]
+source_globs: ["jiuwenswarm/gateway/app_gateway.py"]
+---
+
+# Gateway Config-Save Hot Reload（_on_config_saved：agent.reload_config 重试、重启兜底与副作用）
+
+<!-- kb:knowledge owner=feature-gateway-config-hot-reload facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证入口**
+
+所示代码范围内没有测试引用或断言；验证线索仅有运行时日志：重试 warning（含 attempt 计数与延迟）、失败后的 critical 日志、以及 ValidationError/browser restart/proactive sync 的非致命 warning，可作为人工验证的行为信号。代码中的注释描述了历史故障模式（首登 config.set 前端卡死+1001、沙箱 code 80004），属维护者经验性证据而非测试。
+
+Sources / 来源：[jiuwenswarm/gateway/app_gateway.py:L2065–L2072](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/app_gateway.py#L2065-L2072), [jiuwenswarm/gateway/app_gateway.py:L2113–L2124](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/app_gateway.py#L2113-L2124)
+
+<!-- kb:knowledge owner=feature-gateway-config-hot-reload facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**_on_config_saved 的入口契约**
+
+`_on_config_saved(updated_env_keys, *, env_updates, config_payload, reload_options) -> bool` 是配置保存后的内部入口。它先调用 `client.set_or_update_server_config` 更新网关侧配置，再构造 `ReqMethod.AGENT_RELOAD_CONFIG` 信封发送给 AgentServer，params 含 `config`（保存后的完整快照，Agent 应优先于本地 yaml）、`env`（增量更新，缺失键表示未变），`reload_options` 中的键会经 `**dict(reload_options or {})` 展开覆盖同名字段。返回 True 表示重载成功，False 表示校验错误短路或重试耗尽（后者会安排网关重启）。信封固定 user_id="agentos_test"、session_id="sess_reload"。
+
+Sources / 来源：[jiuwenswarm/gateway/app_gateway.py:L2032–L2086](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/app_gateway.py#L2032-L2086), [jiuwenswarm/gateway/app_gateway.py:L2119–L2125](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/app_gateway.py#L2119-L2125)
+
+<!-- kb:knowledge owner=feature-gateway-config-hot-reload facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**控制流与副作用顺序**
+
+重载请求最多尝试 `_reload_max_retries + 1`（4）次，成功即提前跳出；被拒绝的响应若错误文本含 "ValidationError"/"validation error"/"Field required" 之一则直接返回 False，不重试也不重启；`send_request` 抛出的异常进入重试路径，重试间隔为 `2.0 ** (attempt + 1)` 秒（2、4、8）。重试耗尽后记 critical 日志并调用 `_schedule_gateway_restart(restart_request)`，返回 False。成功后依次执行：`message_handler.update_evolution_auto_save(config_payload)` 刷新内存值（流式热路径不重新读盘）、以 3.0 秒延迟调度 `_schedule_agent_prewarm_sync`、按 env 键条件触发 browser runtime 重启与 proactive cron 同步。
+
+Sources / 来源：[jiuwenswarm/gateway/app_gateway.py:L2057–L2058](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/app_gateway.py#L2057-L2058), [jiuwenswarm/gateway/app_gateway.py:L2090–L2135](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/app_gateway.py#L2090-L2135)
+
+<!-- kb:knowledge owner=feature-gateway-config-hot-reload facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**硬编码参数与触发键集合**
+
+重试次数（3）、退避基数（2.0 秒）和 prewarm 同步延迟（3.0 秒）均为函数内硬编码局部量，非外部可配置项。副作用触发依赖 `updated_env_keys` 集合：仅当与 `browser_runtime_keys`（MODEL/VISION/AUDIO/VIDEO 的 PROVIDER、MODEL_NAME、API_BASE、API_KEY 等 16 个键）有交集时才发送 `BROWSER_RUNTIME_RESTART`；仅当含 `proactive_recommendation_enabled` 时才调用 `sync_proactive_tick_job`。内存刷新与 prewarm 同步不受这些键集合条件控制。重载信封固定复用 `agentos_test` 用户及其 warm instance。
+
+Sources / 来源：[jiuwenswarm/gateway/app_gateway.py:L2039–L2058](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/app_gateway.py#L2039-L2058), [jiuwenswarm/gateway/app_gateway.py:L2137–L2159](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/app_gateway.py#L2137-L2159)
+
+<!-- kb:knowledge owner=feature-gateway-config-hot-reload facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的行为与条件**
+
+功能包括：(1) 配置保存后的全局热重载，向 AgentServer 传完整 config 快照与增量 env；(2) 校验错误短路——错误文本匹配三个子串之一时记 warning 并返回 False，不重试、不重启；(3) 重试耗尽后的网关重启兜底；(4) 成功后的条件副作用——browser runtime 重启仅在 browser 相关 env 键变更时触发且失败仅记 warning（非致命），proactive.tick 任务同步仅在 `proactive_recommendation_enabled` 变更时触发且失败不阻断配置保存。
+
+Sources / 来源：[jiuwenswarm/gateway/app_gateway.py:L2080–L2084](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/app_gateway.py#L2080-L2084), [jiuwenswarm/gateway/app_gateway.py:L2102–L2125](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/app_gateway.py#L2102-L2125), [jiuwenswarm/gateway/app_gateway.py:L2137–L2159](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/app_gateway.py#L2137-L2159)
+
diff --git a/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-gateway-health-check.md b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-gateway-health-check.md
new file mode 100644
index 00000000..3ececf4e
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-gateway-health-check.md
@@ -0,0 +1,46 @@
+---
+title: "Gateway HealthCheck 周期探活服务 (jiuwenswarm/gateway/health_check)"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/health_check/health_check.py:L76-L92, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/health_check/health_check.py:L45-L62, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L3944-L3957, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/health_check/health_check.py:L124-L126, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/health_check/health_check.py:L266-L277, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/health_check/health_check.py:L3-L12, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/health_check/health_check.py:L192-L207, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/health_check/health_check.py:L242-L260, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/health_check/health_check.py:L3-L18, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:tests/unit_tests/gateway/test_app_web_handlers.py:L379-L393]
+feature: "gateway-health-check"
+entry_points: ["jiuwenswarm/gateway/health_check/__init__.py", "jiuwenswarm/gateway/health_check/health_check.py"]
+source_globs: ["jiuwenswarm/gateway/health_check/__init__.py", "jiuwenswarm/gateway/health_check/health_check.py", "jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py"]
+---
+
+# Gateway HealthCheck 周期探活服务 (jiuwenswarm/gateway/health_check)
+
+<!-- kb:knowledge owner=feature-gateway-health-check facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**配置项与运行时更新**
+
+`HealthCheckConfig` 字段：`interval_seconds`（探活间隔秒，MUST > 0）、`timeout_seconds`（单次超时，可选，>0 才生效，否则不包 wait_for）、`channel_id`（默认 `__health_check__`）、`relay_channel_id`（回传 channel，如 "web"，从 .env 的 `HEARTBEAT_RELAY_CHANNEL_ID` 读取，为 None 则不回传）、`active_hours`（`{"start": "HH:MM", "end": "HH:MM"}`，None 表示始终生效）。模块级文档说明配置已从 config.yaml 的 `heartbeat` 段迁移到 `health_check` 段，环境变量保留 `HEARTBEAT_RELAY_CHANNEL_ID` 旧名以不断裂运维。`normalize_active_hours` 处理 YAML 中未加引号的 22:00 被解析为 60 进制数字的问题，转回 "HH:MM"。Web 端 `health_check.set_conf` 处理器校验 params 后调用 `set_health_check_conf` 并经 `update_health_check_in_config` 写回 config.yaml。
+
+Sources / 来源：[jiuwenswarm/gateway/health_check/health_check.py:L76–L92](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/health_check/health_check.py#L76-L92), [jiuwenswarm/gateway/health_check/health_check.py:L45–L62](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/health_check/health_check.py#L45-L62), [jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L3944–L3957](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py#L3944-L3957)
+
+<!-- kb:knowledge owner=feature-gateway-health-check facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证入口**
+
+所示片段中未包含测试文件；可观察的验证途径是运行时日志与代码内状态：模块文档指出成功打 INFO「Gateway health check OK」、失败打 WARNING，代码检查用 `last_tick_ok`/`last_tick_at`。超时路径（`asyncio.TimeoutError`）与通用异常路径分别记录 WARNING 并置 `last_tick_ok=False`。
+
+Sources / 来源：[jiuwenswarm/gateway/health_check/health_check.py:L124–L126](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/health_check/health_check.py#L124-L126), [jiuwenswarm/gateway/health_check/health_check.py:L266–L277](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/health_check/health_check.py#L266-L277)
+
+<!-- kb:knowledge owner=feature-gateway-health-check facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**职责边界与数据流**
+
+HealthCheck 模块承接旧 `gateway/heartbeat/heartbeat.py` 的探活能力，与新 Heartbeat 任务（线程续跑，`gateway/heartbeat/` 下的 models/store/scheduler/controller）严格区分；探活只验证 AgentServer 请求链路，不再读取 `HEARTBEAT.md` 或执行用户任务。`_tick` 用 `e2a_from_agent_fields` 构造 E2A 信封，经 `AgentServerClient.send_request` 发往 AgentServer（可选 `asyncio.wait_for` 超时）。回传是有条件的：仅当配置了 `relay_channel_id` 且注入了 `message_handler` 时，才以 `EventType.HEALTH_CHECK_RELAY` 的 event Message 经 `publish_robot_messages` 回传到指定 channel；模块 docstring 提到默认 web，但配置字段 `relay_channel_id` 默认为 None（不回传）。
+
+Sources / 来源：[jiuwenswarm/gateway/health_check/health_check.py:L3–L12](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/health_check/health_check.py#L3-L12), [jiuwenswarm/gateway/health_check/health_check.py:L192–L207](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/health_check/health_check.py#L192-L207), [jiuwenswarm/gateway/health_check/health_check.py:L242–L260](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/health_check/health_check.py#L242-L260)
+
+<!-- kb:knowledge owner=feature-gateway-health-check facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**迁移兼容与可观测性取舍**
+
+模块从旧 `heartbeat.py` 探活逻辑迁移而来：环境变量沿用旧名 `HEARTBEAT_RELAY_CHANNEL_ID`、relay payload 保留 `heartbeat` 别名字段、Web RPC 中 `heartbeat.get_conf`/`set_conf` 与 `health_check.*` 共享同一处理器，均以兼容旧运维侧与消费者为目的（该兼容范围仅限 get_conf/set_conf，`heartbeat.job.*` 任务方法是独立的另一组方法）。代价是命名双轨：文档明确探活只做连通性检查、不再读取 `HEARTBEAT.md` 或执行用户任务，与新 Heartbeat 任务系统严格区分。可观测性选择日志 + 内部状态而非向 Channel 主动告警：成功打 INFO、失败/超时打 WARNING，循环异常被捕获记日志而不终止循环；Web 端 set_conf 写回 config.yaml 失败仅记 WARNING，写回成功后才调度清除 agent 配置缓存。
+
+Sources / 来源：[jiuwenswarm/gateway/health_check/health_check.py:L3–L18](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/health_check/health_check.py#L3-L18), [jiuwenswarm/gateway/health_check/health_check.py:L242–L260](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/health_check/health_check.py#L242-L260), [jiuwenswarm/gateway/health_check/health_check.py:L266–L277](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/health_check/health_check.py#L266-L277), [jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L3944–L3957](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py#L3944-L3957), [tests/unit_tests/gateway/test_app_web_handlers.py:L379–L393](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/tests/unit_tests/gateway/test_app_web_handlers.py#L379-L393)
+
diff --git a/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-gateway-server-multi-route-ws.md b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-gateway-server-multi-route-ws.md
new file mode 100644
index 00000000..3ca8ba14
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-gateway-server-multi-route-ws.md
@@ -0,0 +1,48 @@
+---
+title: "GatewayServer 多路由 WebSocket 宿主与会话/请求路由表"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/app_gateway.py:L651-L680, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/app_gateway.py:L1040-L1052, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/app_gateway.py:L813-L847, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/app_gateway.py:L1618-L1644, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/app_gateway.py:L1060-L1066, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/app_gateway.py:L1078-L1092, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/app_gateway.py:L1094-L1105, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/app_gateway.py:L1107-L1148, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/app_gateway.py:L1572-L1592, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/app_gateway.py:L943-L978, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/app_gateway.py:L979-L1007]
+feature: "gateway-server-multi-route-ws"
+entry_points: ["jiuwenswarm/gateway/app_gateway.py"]
+source_globs: ["jiuwenswarm/gateway/app_gateway.py", "jiuwenswarm/gateway/channel_manager/channel_manager.py", "jiuwenswarm/gateway/routing/route_binding.py", "jiuwenswarm/gateway/channel_manager/base.py", "jiuwenswarm/gateway/routing/keys.py"]
+---
+
+# GatewayServer 多路由 WebSocket 宿主与会话/请求路由表
+
+<!-- kb:knowledge owner=feature-gateway-server-multi-route-ws facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**GatewayServerConfig 与 RouteConfig**
+
+`GatewayServerConfig` 默认 enabled=True、host="127.0.0.1"、port=19001；`__post_init__` 在 routes 为空且同时给出 path 和 channel_id 时，兼容地合成单条 RouteConfig。每条 `RouteConfig` 除 local_handlers 字典和 forward_methods/forward_no_local_handler_methods 外，还可挂 inbound/outbound_interceptor、cleanup/disconnect/session_bind_handler 钩子，以及 V2 新增的 ws_channel（委托注册的外部 Channel，如 tui 的 TuiChannel；None 表示该 route 不委托）。路由匹配 `_resolve_route` 按精确路径并容忍尾部斜杠变体。
+
+Sources / 来源：[jiuwenswarm/gateway/app_gateway.py:L651–L680](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/app_gateway.py#L651-L680), [jiuwenswarm/gateway/app_gateway.py:L1040–L1052](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/app_gateway.py#L1040-L1052)
+
+<!-- kb:knowledge owner=feature-gateway-server-multi-route-ws facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**2↔3 元组双向兜底与委托注册的职责拆分**
+
+Inference / 设计推断（非作者历史意图）：
+
+`_lookup_client` 在精确键 MISS 后做防御性双向兜底（3 元组降级查 2 元组、2 元组升级扫描前缀匹配的 3 元组、再裸 scope 兜底），注释引用设计 §6.3，动机是链路某环节丢 agent_ref 时不至于响应 dropped——代价是查找语义变宽，同 session 多 agent_ref 场景下兜底可能命中非严格对应连接（此为推断）。ws_channel 路由上，GatewayServer 保留自身表做入站响应反查，但把出站 chunk 精确路由委托给 TuiChannel 的五维索引，形成双路由表并存的职责拆分。
+
+Sources / 来源：[jiuwenswarm/gateway/app_gateway.py:L813–L847](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/app_gateway.py#L813-L847), [jiuwenswarm/gateway/app_gateway.py:L1618–L1644](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/app_gateway.py#L1618-L1644)
+
+<!-- kb:knowledge owner=feature-gateway-server-multi-route-ws facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**公共入口与回包契约**
+
+`GatewayServer(config, router)` 构造后通过 `register_local_handler(path, method, handler)` 注册本地方法（路由不存在时自动合成 RouteConfig），`start()`/`stop()`/`wait_until_closed()` 管理生命周期。回包接口 `send_response(ws, req_id, ok, payload, error, code)` 发送 `type=res` 帧：失败时必附 `error`（缺省 "request failed"），`code` 仅在传入真值时才写入帧，是可选字段。`send_event(ws, event, payload)` 发送 `type=event` 帧；两者发送失败均只记 debug 日志不抛出。
+
+Sources / 来源：[jiuwenswarm/gateway/app_gateway.py:L1060–L1066](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/app_gateway.py#L1060-L1066), [jiuwenswarm/gateway/app_gateway.py:L1078–L1092](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/app_gateway.py#L1078-L1092), [jiuwenswarm/gateway/app_gateway.py:L1094–L1105](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/app_gateway.py#L1094-L1105), [jiuwenswarm/gateway/app_gateway.py:L1107–L1148](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/app_gateway.py#L1107-L1148)
+
+<!-- kb:knowledge owner=feature-gateway-server-multi-route-ws facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**会话独占的两道防线：实时拒绝与 pending 挂起提升**
+
+同 session 多连接冲突由两段逻辑分别处理。forward 路径中，若 session_key 已绑定到另一个仍活跃的连接，直接回 `SESSION_IN_USE` 错误帧并终止该请求，不会把新连接挂起（app_gateway.py:1572-1588）。挂起发生在 `_bind_route_session_client`：绑定冲突时若新 ws 仍打开，则记入 `_pending_session_clients` 并返回 False；旧连接断开清理后由 `_promote_pending_session_client` 提升——仅当 pending ws 仍打开且当前无其他活跃占用者时写入 `_session_to_client`，且仅在 route 配置了 session_bind_handler 时才调用该钩子。
+
+Sources / 来源：[jiuwenswarm/gateway/app_gateway.py:L1572–L1592](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/app_gateway.py#L1572-L1592), [jiuwenswarm/gateway/app_gateway.py:L943–L978](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/app_gateway.py#L943-L978), [jiuwenswarm/gateway/app_gateway.py:L979–L1007](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/app_gateway.py#L979-L1007)
+
diff --git a/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-im-attachment-persist-hook-969909e1.md b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-im-attachment-persist-hook-969909e1.md
new file mode 100644
index 00000000..262b811d
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-im-attachment-persist-hook-969909e1.md
@@ -0,0 +1,54 @@
+---
+title: "IM Attachment Persist Hook (E2A + HTTP Bridge) — ChannelManager wiring"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/channel_manager.py:L163-L183, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/channel_manager.py:L230-L244, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/channel_manager.py:L206-L229, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/channel_manager.py:L260-L262, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/channel_manager.py:L127-L162, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/channel_manager.py:L176-L185, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/channel_manager.py:L223-L229, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/channel_manager.py:L186-L193, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/channel_manager.py:L195-L219, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/channel_manager.py:L127-L147, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/channel_manager.py:L163-L185, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/channel_manager.py:L195-L229, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/channel_manager.py:L266-L272]
+feature: "im-attachment-persist-hook-969909e1"
+entry_points: ["jiuwenswarm/gateway/channel_manager/channel_manager.py"]
+source_globs: ["jiuwenswarm/gateway/channel_manager/channel_manager.py"]
+---
+
+# IM Attachment Persist Hook (E2A + HTTP Bridge) — ChannelManager wiring
+
+<!-- kb:knowledge owner=feature-im-attachment-persist-hook-969909e1 facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**Supported routing modes and explicit deferral**
+
+The hook supports single-user IM deployments with an E2A or HTTP-bridge-capable agent client, returning persisted-file metadata including the AgentServer-side deduplicated name. IM AgentOS multi-user routing is explicitly deferred: for AgentOS-routing clients a deliberately failing hook is installed that raises "IM attachment routing requires an authenticated AgentOS user_id", because the inbound IM protocol does not yet carry an authenticated per-message user_id routing key.
+
+Sources / 来源：[jiuwenswarm/gateway/channel_manager/channel_manager.py:L163–L183](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/channel_manager.py#L163-L183), [jiuwenswarm/gateway/channel_manager/channel_manager.py:L230–L244](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/channel_manager.py#L230-L244)
+
+<!-- kb:knowledge owner=feature-im-attachment-persist-hook-969909e1 facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**Fail-hard over local fallback (decision D6)**
+
+On any non-shared-directory client the hook never falls back to writing on the Gateway: upload or E2A failures raise so the message fails as retryable, trading availability for correctness — a local fallback would silently place attachments in the Gateway deployment directory instead of the target AgentServer's injection directory. The size-based transport split is a second deliberate tradeoff (design §10.5 per the comment): small attachments pay base64/E2A overhead while large ones avoid a `PayloadTooBig` error that would take down the whole Gateway↔AgentServer WebSocket connection.
+
+Sources / 来源：[jiuwenswarm/gateway/channel_manager/channel_manager.py:L206–L229](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/channel_manager.py#L206-L229), [jiuwenswarm/gateway/channel_manager/channel_manager.py:L260–L262](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/channel_manager.py#L260-L262)
+
+<!-- kb:knowledge owner=feature-im-attachment-persist-hook-969909e1 facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**Hook injection and call contract**
+
+The entry point is `_try_wire_file_persist_hook`, invoked from both `register_channel` and `register_channel_with_inbound` (channel_manager.py:L127-L147). Injection occurs only when the channel exposes `set_file_persist_hook` and the MessageHandler has an `agent_client`; otherwise it returns silently (L157-L162). The installed hook takes `(content, category, filename)` and returns a metadata dict. Failure behavior is conditional per branch: AgentOS-routing clients get a hook that always raises `RuntimeError` (L176-L183); legacy shared-directory clients get no hook at all (L184-L185); on the installed persist hook, a failed HTTP upload (L223-L229) or failed E2A call (L260-L261) is converted to `RuntimeError`, and the E2A success path returns the agent payload as-is without field validation (L262).
+
+Sources / 来源：[jiuwenswarm/gateway/channel_manager/channel_manager.py:L127–L162](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/channel_manager.py#L127-L162), [jiuwenswarm/gateway/channel_manager/channel_manager.py:L176–L185](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/channel_manager.py#L176-L185), [jiuwenswarm/gateway/channel_manager/channel_manager.py:L223–L229](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/channel_manager.py#L223-L229), [jiuwenswarm/gateway/channel_manager/channel_manager.py:L260–L262](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/channel_manager.py#L260-L262)
+
+<!-- kb:knowledge owner=feature-im-attachment-persist-hook-969909e1 facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**Derived identifiers, not user settings**
+
+Within this file the hook is governed entirely by runtime discovery (channel capability, agent_client routing type), not by user-facing configuration keys; the ChannelManager `config` dict is unrelated to hook wiring. The storage platform identifier is derived from the channel's `channel_id`, lowercased and sanitized so only alphanumerics, `_` and `-` survive — e.g. the `feishu_enterprise:<bot_key>` form's colon cannot serve as a directory name — falling back to `im` when empty (L186-L193). The HTTP-bridge target path `agent/workspace/<platform>_files/downloads/<category>/<filename>` is fixed in code, and the transport threshold comes from `E2A_PAYLOAD_MAX_BYTES` imported from `agent_http_bridge` (L201-L219).
+
+Sources / 来源：[jiuwenswarm/gateway/channel_manager/channel_manager.py:L186–L193](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/channel_manager.py#L186-L193), [jiuwenswarm/gateway/channel_manager/channel_manager.py:L195–L219](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/channel_manager.py#L195-L219)
+
+<!-- kb:knowledge owner=feature-im-attachment-persist-hook-969909e1 facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**Hook wiring points and routing-mode dispatch**
+
+ChannelManager wires the attachment persist hook at two registration points: `register_channel` and `register_channel_with_inbound` both call `_try_wire_file_persist_hook` after registering the channel, while `register_external_channel` registers the instance without any callback or hook wiring. Inside `_try_wire_file_persist_hook`, three routing modes are distinguished via `e2a_proxy` predicates: AgentOS-routing clients get an explicitly failing hook (no authenticated user_id routing key, deferred), legacy shared-directory clients get no hook (FileService keeps local persistence), and other clients get a dual-transport hook — small payloads go base64 over E2A `IM_FILE_PERSIST` to the AgentServer, payloads over `E2A_PAYLOAD_MAX_BYTES` go through the authenticated HTTP bridge to `agent/workspace/<platform>_files/downloads/<category>/<filename>`, with failures raising rather than falling back to Gateway-local disk.
+
+Sources / 来源：[jiuwenswarm/gateway/channel_manager/channel_manager.py:L127–L147](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/channel_manager.py#L127-L147), [jiuwenswarm/gateway/channel_manager/channel_manager.py:L163–L185](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/channel_manager.py#L163-L185), [jiuwenswarm/gateway/channel_manager/channel_manager.py:L195–L229](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/channel_manager.py#L195-L229), [jiuwenswarm/gateway/channel_manager/channel_manager.py:L266–L272](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/channel_manager.py#L266-L272)
+
diff --git a/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-im-channel-hot-reconfig.md b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-im-channel-hot-reconfig.md
new file mode 100644
index 00000000..ffc01162
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-im-channel-hot-reconfig.md
@@ -0,0 +1,38 @@
+---
+title: "IM Channel Hot Reconfiguration (_apply_channel_config lifecycle across 11 channels)"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/app_gateway.py:L2466-L2517, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/app_gateway.py:L2576-L2643, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/app_gateway.py:L2552-L2564, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/app_gateway.py:L2591-L2643, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/app_gateway.py:L2669-L2721, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L4023-L4046, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L4277-L4288, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L4490-L4503]
+feature: "im-channel-hot-reconfig"
+entry_points: ["jiuwenswarm/gateway/app_gateway.py"]
+source_globs: ["jiuwenswarm/gateway/app_gateway.py", "jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py"]
+---
+
+# IM Channel Hot Reconfiguration (_apply_channel_config lifecycle across 11 channels)
+
+<!-- kb:knowledge owner=feature-im-channel-hot-reconfig facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**Diff-driven stop/rebuild loop over channel_manager and IM adapters**
+
+Control flow: `_should_restart_channel` compares old vs new per-channel config dicts (restart when presence differs or contents differ) and union with `channel_manager.pop_channel_restart_pending()` for forced restarts; only channels in `changed_channels` are torn down and rebuilt (app_gateway.py:2466-2473, 2550-2573). Teardown is centralized in `_stop_channel`: cancel the asyncio task (5s wait, or background wait), `channel.stop()` with a 10s timeout, then `channel_manager.unregister_channel`; feishu/xiaoyi multi-app instances are discovered via `channel_manager.pop_channels_by_id`, and digital-avatar adapters are unregistered/registered on `im_inbound`/`im_outbound` buses.
+
+Sources / 来源：[jiuwenswarm/gateway/app_gateway.py:L2466–L2517](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/app_gateway.py#L2466-L2517), [jiuwenswarm/gateway/app_gateway.py:L2576–L2643](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/app_gateway.py#L2576-L2643)
+
+<!-- kb:knowledge owner=feature-im-channel-hot-reconfig facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的频道与实例形态**
+
+重配循环覆盖 11 个频道键：feishu、feishu_enterprise、xiaoyi、dingtalk、telegram、whatsapp、discord、slack、wecom、wechat、ssh（app_gateway.py:2552-2564）。feishu 支持 `apps` 列表多实例，所有实例共享 channel_id "feishu"，各自 `asyncio.create_task(channel.start())` 且任务挂在 `channel.start_task` 上；`group_digital_avatar` 为真时创建 FeishuIMPlatformAdapter 并注册到 im_inbound/im_outbound（app_gateway.py:2591-2643）。feishu_enterprise 以 bot_key→配置的映射管理，channel_id 为 `feishu_enterprise:{app_id}`，同样支持数字分身 adapter（app_gateway.py:2669-2721）。
+
+Sources / 来源：[jiuwenswarm/gateway/app_gateway.py:L2552–L2564](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/app_gateway.py#L2552-L2564), [jiuwenswarm/gateway/app_gateway.py:L2591–L2643](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/app_gateway.py#L2591-L2643), [jiuwenswarm/gateway/app_gateway.py:L2669–L2721](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/app_gateway.py#L2669-L2721)
+
+<!-- kb:knowledge owner=feature-im-channel-hot-reconfig facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**写配置前的参数校验**
+
+Web 处理器在写配置前做输入校验：非 dict 的 params 返回 `BAD_REQUEST`（如 feishu set_conf、whatsapp/discord/slack/wecom/wechat set_conf，app_web_handlers.py:4023-4031, 4277-4285）。wechat set_conf 额外调用 `_validate_wechat_numeric_params`，在 `set_conf` 之前拒绝负数/0/极大值/浮点越界/非数字的数值参数并返回 `BAD_REQUEST`（app_web_handlers.py:4490-4500）。feishu set_conf 在持久化前先 `_normalize_feishu_conf` 归一化 apps（app_web_handlers.py:4040-4046）。
+
+Sources / 来源：[jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L4023–L4046](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py#L4023-L4046), [jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L4277–L4288](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py#L4277-L4288), [jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L4490–L4503](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py#L4490-L4503)
+
diff --git a/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-im-feishu.md b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-im-feishu.md
index 6832c90d..197452e1 100644
--- a/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-im-feishu.md
+++ b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-im-feishu.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/国内频道.md
 feature: "im-feishu"
 entry_points: ["jiuwenswarm/gateway/channel_manager/im_platforms/feishu/feishu_connect.py"]
-source_globs: ["jiuwenswarm/gateway/channel_manager/im_platforms/feishu/feishu_connect.py", "jiuwenswarm/gateway/channel_manager/im_platforms/feishu/*"]
+source_globs: ["jiuwenswarm/gateway/channel_manager/im_platforms/feishu/feishu_connect.py", "jiuwenswarm/gateway/channel_manager/im_platforms/feishu/*", "jiuwenswarm/gateway/channel_manager/channel_manager.py", "jiuwenswarm/common/config.py", "jiuwenswarm/gateway/channel_manager/im_platforms/feishu/feishu_streaming_card.py", "jiuwenswarm/gateway/channel_manager/im_platforms/feishu/feishu_file_service.py", "jiuwenswarm/gateway/channel_manager/im_platforms/platform_adapter/message.py", "jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/channels/channelFormItems.ts", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/channels/channelRequirements.ts", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/channels/useChannelForm.ts", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/channels/useSettingsChannelsController.ts"]
 ---
 
 # 飞书 频道 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-im-wechat.md b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-im-wechat.md
index e6299827..fe2d564a 100644
--- a/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-im-wechat.md
+++ b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-im-wechat.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/国内频道.md
 feature: "im-wechat"
 entry_points: ["jiuwenswarm/gateway/channel_manager/im_platforms/wechat/wechat_connect.py"]
-source_globs: ["jiuwenswarm/gateway/channel_manager/im_platforms/wechat/wechat_connect.py", "jiuwenswarm/gateway/channel_manager/im_platforms/wechat/*"]
+source_globs: ["jiuwenswarm/gateway/channel_manager/im_platforms/wechat/wechat_connect.py", "jiuwenswarm/gateway/channel_manager/im_platforms/wechat/*", "jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py"]
 ---
 
 # 微信 频道 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-im-wecom.md b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-im-wecom.md
index 529de9d4..3547c17f 100644
--- a/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-im-wecom.md
+++ b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-im-wecom.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/国内频道.md
 feature: "im-wecom"
 entry_points: ["jiuwenswarm/gateway/channel_manager/im_platforms/wecom/wecom_connect.py"]
-source_globs: ["jiuwenswarm/gateway/channel_manager/im_platforms/wecom/wecom_connect.py", "jiuwenswarm/gateway/channel_manager/im_platforms/wecom/*"]
+source_globs: ["jiuwenswarm/gateway/channel_manager/im_platforms/wecom/wecom_connect.py", "jiuwenswarm/gateway/channel_manager/im_platforms/wecom/*", "jiuwenswarm/gateway/channel_manager/im_platforms/wecom/wecom_file_service.py", "jiuwenswarm/gateway/channel_manager/im_platforms/wecom/wecom_im_adapter.py"]
 ---
 
 # 企业微信 频道 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-im-whatsapp.md b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-im-whatsapp.md
index 4b72e106..495dbc68 100644
--- a/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-im-whatsapp.md
+++ b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-im-whatsapp.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/海外频道.md
 feature: "im-whatsapp"
 entry_points: ["jiuwenswarm/gateway/channel_manager/im_platforms/whatsapp/whatsapp_connect.py"]
-source_globs: ["jiuwenswarm/gateway/channel_manager/im_platforms/whatsapp/whatsapp_connect.py", "jiuwenswarm/gateway/channel_manager/im_platforms/whatsapp/*"]
+source_globs: ["jiuwenswarm/gateway/channel_manager/im_platforms/whatsapp/whatsapp_connect.py", "jiuwenswarm/gateway/channel_manager/im_platforms/whatsapp/*", "jiuwenswarm/scripts/whatsapp-bridge.js"]
 ---
 
 # WhatsApp 频道 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-im-xiaoyi.md b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-im-xiaoyi.md
index d6704ab4..ca0e21c3 100644
--- a/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-im-xiaoyi.md
+++ b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-im-xiaoyi.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/国内频道.md
 feature: "im-xiaoyi"
 entry_points: ["jiuwenswarm/gateway/channel_manager/im_platforms/xiaoyi/xiaoyi_connect.py"]
-source_globs: ["jiuwenswarm/gateway/channel_manager/im_platforms/xiaoyi/xiaoyi_connect.py", "jiuwenswarm/gateway/channel_manager/im_platforms/xiaoyi/*"]
+source_globs: ["jiuwenswarm/gateway/channel_manager/im_platforms/xiaoyi/xiaoyi_connect.py", "jiuwenswarm/gateway/channel_manager/im_platforms/xiaoyi/*", "jiuwenswarm/gateway/channel_manager/im_platforms/xiaoyi/xiaoyi_utils/formatter.py", "jiuwenswarm/gateway/channel_manager/im_platforms/xiaoyi/xiaoyi_utils/media.py", "jiuwenswarm/gateway/channel_manager/im_platforms/xiaoyi/xiaoyi_utils/push.py"]
 ---
 
 # 小艺 频道 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-locale-conf-rpc.md b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-locale-conf-rpc.md
new file mode 100644
index 00000000..de3be8f0
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-locale-conf-rpc.md
@@ -0,0 +1,62 @@
+---
+title: "界面语言配置 RPC（preferred_language）— Gateway Web Handler"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L3824-L3850, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L3860-L3865, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L3724-L3751, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L3803-L3822, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L3841-L3865, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L3804-L3816, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L3851-L3859, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L3795-L3822, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L3804-L3822, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L3851-L3865, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:tests/unit_tests/gateway/test_app_web_handlers.py:L16-L37, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:tests/unit_tests/gateway/test_app_web_handlers.py:L545-L577, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:tests/unit_tests/gateway/test_app_web_handlers.py:L427-L454]
+feature: "locale-conf-rpc"
+entry_points: ["jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py"]
+source_globs: ["jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py"]
+---
+
+# 界面语言配置 RPC（preferred_language）— Gateway Web Handler
+
+<!-- kb:knowledge owner=feature-locale-conf-rpc facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的行为与边界**
+
+功能是界面语言的读取与更新，语言集合固定为中文/英文两种，输入做大小写与空白归一化（`strip().lower()`），因此 `"EN "`、`"Zh"` 均可被接受。转发路径下语言状态由所选 AgentServer 的用户目录持有（set_conf 的 docstring 称 "Update preferred language in the selected AgentServer directory"），依赖 `jiuwenswarm.gateway.routing.e2a_proxy` 与 `jiuwenswarm.common.schema.message.ReqMethod` 两个协作方。
+
+Sources / 来源：[jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L3824–L3850](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py#L3824-L3850), [jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L3860–L3865](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py#L3860-L3865)
+
+<!-- kb:knowledge owner=feature-locale-conf-rpc facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**双路径路由：本地配置 vs E2A 代理**
+
+两个 handler 都用 `_resolve(agent_client)` 解析当前 Agent 客户端，并在其为 `None` 或被 `is_legacy_shared_directory_client` 判定为 legacy 共享目录客户端时走本地路径：get 从 `get_config()` 读 `preferred_language`，set 调 `update_preferred_language_in_config(lang)` 写回。注意 set handler 先在参数校验（L3832–L3850）通过后才于 L3851 调 `_resolve`。非 legacy 时经 `proxy_unary_request` 以 `ReqMethod.LOCALE_GET_CONF` / `LOCALE_SET_CONF` 转发到所选 AgentServer，携带 `session_id` 与 `user_id`，set 只透传归一化后的 `{"preferred_language": lang}`；这与 document.persist/document.formats 等共用同一 E2A 代理机制。
+
+Sources / 来源：[jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L3724–L3751](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py#L3724-L3751), [jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L3803–L3822](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py#L3803-L3822), [jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L3841–L3865](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py#L3841-L3865)
+
+<!-- kb:knowledge owner=feature-locale-conf-rpc facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**preferred_language 配置项与取值规则**
+
+配置键名为 `preferred_language`。本地 get 分支读取 `get_config()` 中的该键，空值回落 `"zh"`，经 `strip().lower()` 后不在 `("zh", "en")` 内也回落 `"zh"`——这一默认与回落逻辑仅适用于本地/legacy 分支，代理读路径的行为未在所示代码中体现。本地 set 分支通过 `update_preferred_language_in_config(lang)` 持久化（L3857 的日志措辞为"写回 config.yaml 失败"，持久化目标的进一步细节未在所示范围内展示），写失败时 RPC 返回 `ok=False`、`code="INTERNAL_ERROR"`。
+
+Sources / 来源：[jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L3804–L3816](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py#L3804-L3816), [jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L3851–L3859](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py#L3851-L3859)
+
+<!-- kb:knowledge owner=feature-locale-conf-rpc facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**locale.get_conf / locale.set_conf 入口契约**
+
+两个 handler 签名均为 `(ws, req_id, params, session_id, user_id=None)`。`locale.set_conf` 要求 params 为 dict 且 `preferred_language` 为字符串，经 `strip().lower()` 归一化后必须是 `"zh"` 或 `"en"`，否则返回 `ok=False`、`code="BAD_REQUEST"`（含非 dict params 与非字符串两种错误）；校验通过后走本地写回或 E2A 代理。`locale.get_conf` 的本地分支成功时返回 `ok=True`、`payload={"preferred_language": lang}`；本地分支异常时返回 `ok=False`、`code="INTERNAL_ERROR"`。所示代码范围未包含 RPC 方法名到 handler 的注册映射，无法据此确认挂载方式。
+
+Sources / 来源：[jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L3795–L3822](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py#L3795-L3822), [jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L3824–L3850](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py#L3824-L3850)
+
+<!-- kb:knowledge owner=feature-locale-conf-rpc facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**本地白名单回退仅限本地分支；代理分支直接转发**
+
+get 的白名单校验与静默回退（空值或非法值回落 `"zh"`）只出现在本地/legacy 分支；代理分支通过 `proxy_unary_request` 以空 params 转发 `ReqMethod.LOCALE_GET_CONF`，其响应行为不在所示代码内。因此不能概括为「读路径总能返回可用语言」——本地分支在读配置抛异常时即返回 `INTERNAL_ERROR`。set 侧则在 Gateway 前置校验语言值，非法输入直接拒绝而不透传；本地写回 `update_preferred_language_in_config` 失败同样以 `INTERNAL_ERROR` 上报（L3856–L3858 的日志措辞为「写回 config.yaml 失败」，持久化目标细节未在所示范围展示）。
+
+Sources / 来源：[jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L3804–L3822](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py#L3804-L3822), [jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L3851–L3865](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py#L3851-L3865)
+
+<!-- kb:knowledge owner=feature-locale-conf-rpc facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**Web handler 单测模式与 locale 覆盖情况**
+
+验证入口是 `tests/unit_tests/gateway/test_app_web_handlers.py`：用例通过 `_register_web_handlers(WebHandlersBindParams(channel=FakeWebChannel(), ...))` 完成绑定后，直接以 `(ws, req_id, params, session_id[, user_id])` 调用 `channel.methods["<method>"]`，并对响应字典断言 `ok`/`code`/`payload`（如 session.list 的 E2A 转发契约、heartbeat 的 SERVICE_UNAVAILABLE/NOT_FOUND 错误码）。所示 FakeWebChannel 仅显式展示 `channel_id` 与 `methods` 字典（L34–L37），各用例断言的 `channel.responses[-1]` 依赖其未在摘录内展示的记录行为。在该测试文件的所示摘录中未出现针对 `locale.get_conf` / `locale.set_conf` 的用例——这是对所示片段的有界观察，不代表整个仓库或本文件其余部分没有 locale 测试。
+
+Sources / 来源：[tests/unit_tests/gateway/test_app_web_handlers.py:L16–L37](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/tests/unit_tests/gateway/test_app_web_handlers.py#L16-L37), [tests/unit_tests/gateway/test_app_web_handlers.py:L545–L577](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/tests/unit_tests/gateway/test_app_web_handlers.py#L545-L577), [tests/unit_tests/gateway/test_app_web_handlers.py:L427–L454](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/tests/unit_tests/gateway/test_app_web_handlers.py#L427-L454)
+
diff --git a/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-process-cli.md b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-process-cli.md
index 571e2c2a..f48d4518 100644
--- a/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-process-cli.md
+++ b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-process-cli.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/命令行指令.md
 feature: "process-cli"
 entry_points: ["jiuwenswarm/channels/process_cli/app.py"]
-source_globs: ["jiuwenswarm/channels/process_cli/app.py", "jiuwenswarm/channels/process_cli/*.py"]
+source_globs: ["jiuwenswarm/channels/process_cli/app.py", "jiuwenswarm/channels/process_cli/*.py", "jiuwenswarm/channels/process_cli/machine_signals.py", "jiuwenswarm/channels/process_cli/control_commands.py", "jiuwenswarm/channels/process_cli/display_context.py", "jiuwenswarm/channels/process_cli/duplex_control.py", "jiuwenswarm/channels/process_cli/duplex_protocol.py", "jiuwenswarm/channels/process_cli/duplex_input.py", "jiuwenswarm/channels/process_cli/main.py", "jiuwenswarm/channels/process_cli/render.py", "jiuwenswarm/channels/process_cli/client.py", "jiuwenswarm/channels/process_cli/live_input.py", "jiuwenswarm/channels/process_cli/live_layout.py", "jiuwenswarm/channels/process_cli/machine.py", "jiuwenswarm/channels/process_cli/protocol/model.py", "jiuwenswarm/channels/process_cli/protocol/version.py", "jiuwenswarm/channels/process_cli/protocol/__init__.py", "jiuwenswarm/channels/process_cli/protocol/jsonl.py", "jiuwenswarm/channels/process_cli/protocol/query.py", "jiuwenswarm/channels/process_cli/query.py", "jiuwenswarm/channels/process_cli/query_entry.py", "jiuwenswarm/channels/process_cli/repl.py", "jiuwenswarm/channels/process_cli/ui.py", "jiuwenswarm/channels/process_cli/machine_result.py", "jiuwenswarm/channels/process_cli/session_guard.py", "jiuwenswarm/channels/process_cli/commands.py", "jiuwenswarm/channels/process_cli/prompt.py"]
 ---
 
 # 机器执行与本地 CLI 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-ssh.md b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-ssh.md
index aa1d8921..3cf0ed1e 100644
--- a/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-ssh.md
+++ b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-ssh.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/频道.md
 feature: "ssh"
 entry_points: ["jiuwenswarm/gateway/channel_manager/protocol/ssh/ssh_connect.py"]
-source_globs: ["jiuwenswarm/gateway/channel_manager/protocol/ssh/ssh_connect.py", "jiuwenswarm/gateway/channel_manager/protocol/ssh/*.py"]
+source_globs: ["jiuwenswarm/gateway/channel_manager/protocol/ssh/ssh_connect.py", "jiuwenswarm/gateway/channel_manager/protocol/ssh/*.py", "jiuwenswarm/extensions/agentos/auth/ssh_authenticator.py", "jiuwenswarm/extensions/agentos/auth/ssh_key_issuer.py", "jiuwenswarm/extensions/agentos/auth/ssh_key_registry.py", "jiuwenswarm/extensions/agentos/agentos_router/router_client.py", "jiuwenswarm/extensions/agentos/agentos_router/ssh_relay.py", "jiuwenswarm/extensions/agentos/auth/common.py", "jiuwenswarm/extensions/agentos/auth/credential_authenticator.py", "jiuwenswarm/gateway/app_gateway.py", "jiuwenswarm/gateway/channel_manager/protocol/ssh/__init__.py", "jiuwenswarm/gateway/channel_manager/protocol/ssh/config.py", "jiuwenswarm/gateway/channel_manager/protocol/ssh/server.py"]
 ---
 
 # SSH 频道与远程终端 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-thirdagent-list-switch.md b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-thirdagent-list-switch.md
new file mode 100644
index 00000000..6c88633c
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/gateway-channels/feature-thirdagent-list-switch.md
@@ -0,0 +1,56 @@
+---
+title: "3rdagent.list / 3rdagent.switch 第三方智能体切换"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/agentos/agentos_router/router_client.py:L1893-L1909, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/agentos/agentos_router/router_client.py:L1947-L1975, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/routing/third_agent.py:L3-L7, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/agentos/agentos_router/router_client.py:L1878-L1896, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/common/client/third_agent.py:L63-L82, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/agentos/agentos_router/router_client.py:L1910-L1921, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/common/client/third_agent.py:L24-L49, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/common/client/third_agent.py:L52-L82, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/agentos/agentos_router/router_client.py:L2013-L2021, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/agentos/agentos_router/router_client.py:L1844-L1864, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/agentos/agentos_router/router_client.py:L2019-L2036, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/agentos/agentos_router/router_client.py:L1790-L1796, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/common/client/third_agent.py:L3-L15, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/routing/third_agent.py:L3-L17, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/agentos/agentos_router/router_client.py:L1817-L1842, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/extensions/agentos/agentos_router/router_client.py:L1910-L1929]
+feature: "thirdagent-list-switch"
+entry_points: ["jiuwenswarm/extensions/agentos/agentos_router/router_client.py"]
+source_globs: ["jiuwenswarm/extensions/agentos/agentos_router/router_client.py", "jiuwenswarm/common/client/third_agent.py", "jiuwenswarm/gateway/routing/third_agent.py"]
+---
+
+# 3rdagent.list / 3rdagent.switch 第三方智能体切换
+
+<!-- kb:knowledge owner=feature-thirdagent-list-switch facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**设计取舍**
+
+switch 采用多层 fail-fast：在创建 sandbox 之前先校验 SSH 端点和密钥签发，注释明示理由——没有密钥客户端过不了公钥认证，"成功"的 switch 也无法使用。就绪等待采取保守策略：代码注释指出 create 返回不代表端口探针成功，先等 GET status=running 再探南向 SSH，避免 sshd 未监听时立刻掐断连接；实例确认不存在/停止时强制清理残留 runtime，让下次 switch 能重建（sshd 未就绪则仍走保守的 SSH_NOT_READY 分支）。契约下沉到 `common/client` 并在 gateway 侧 re-export，是保留侧与 Gateway 仓共用契约、又保持旧 import 路径兼容的折中（module docstring 自述）。
+
+Sources / 来源：[jiuwenswarm/extensions/agentos/agentos_router/router_client.py:L1893–L1909](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/agentos/agentos_router/router_client.py#L1893-L1909), [jiuwenswarm/extensions/agentos/agentos_router/router_client.py:L1947–L1975](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/agentos/agentos_router/router_client.py#L1947-L1975), [jiuwenswarm/gateway/routing/third_agent.py:L3–L7](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/routing/third_agent.py#L3-L7)
+
+<!-- kb:knowledge owner=feature-thirdagent-list-switch facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证入口**
+
+Inference / 设计推断（非作者历史意图）：
+
+在本次提供的源码片段中没有出现针对 `thirdagent_list` / `thirdagent_switch` 的测试代码，无法从所示证据确认测试入口或覆盖情况。可观察的行为锚点（可用于人工或测试验证）：空 user_id 的 `BAD_REQUEST` 返回、`UnsupportedThirdAgent` 的 `UNSUPPORTED` 返回、以及 builtin swarm 路径不创建 sandbox 而直接返回 READY payload。
+
+Sources / 来源：[jiuwenswarm/extensions/agentos/agentos_router/router_client.py:L1878–L1896](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/agentos/agentos_router/router_client.py#L1878-L1896), [jiuwenswarm/common/client/third_agent.py:L63–L82](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/common/client/third_agent.py#L63-L82), [jiuwenswarm/extensions/agentos/agentos_router/router_client.py:L1910–L1921](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/agentos/agentos_router/router_client.py#L1910-L1921)
+
+<!-- kb:knowledge owner=feature-thirdagent-list-switch facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**ThirdAgent 契约与路由实现**
+
+`ThirdAgent` 是南北向共用抽象契约（Gateway 仓另持副本），声明 `thirdagent_list(user_id, current_agent_type, access_mode)` 与 `thirdagent_switch(user_id, agent_type, session_id, params)` 两个抽象方法；`UnsupportedThirdAgent` 作为无扩展注册时的默认实现，两个方法均返回 `ok=False`、`code="UNSUPPORTED"`。AgentOSRouter 的实现里，空 `user_id` 返回 `BAD_REQUEST`，非法 `agent_type` 规范化失败返回 `UNSUPPORTED_AGENT_TYPE`，agent 创建类异常映射为 `INTERNAL_ERROR`。switch 成功 payload 含 `agent_id/agent_type/sandbox_id/status` 并合并 SSH 端点字段；仅当配置了密钥签发器时才附加 `ssh_private_key` 字段，未注入签发器时 `_ephemeral_ssh_key_fields` 返回空映射。
+
+Sources / 来源：[jiuwenswarm/common/client/third_agent.py:L24–L49](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/common/client/third_agent.py#L24-L49), [jiuwenswarm/common/client/third_agent.py:L52–L82](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/common/client/third_agent.py#L52-L82), [jiuwenswarm/extensions/agentos/agentos_router/router_client.py:L1878–L1896](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/agentos/agentos_router/router_client.py#L1878-L1896), [jiuwenswarm/extensions/agentos/agentos_router/router_client.py:L2013–L2021](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/agentos/agentos_router/router_client.py#L2013-L2021)
+
+<!-- kb:knowledge owner=feature-thirdagent-list-switch facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**运行前提配置**
+
+switch 依赖北向 SSH 频道配置：`_ssh_endpoint_fields` 从 `channels.ssh` 的 listen ip/port 生成 `ssh_ip`/`ssh_port`，缺失或不合法（空 ip 或端口 ≤0）时在创建 sandbox 之前 fail-fast，返回 `SSH_ENDPOINT_UNAVAILABLE`，错误信息指明需启用 `channels.ssh` 并设置 `listen_host`/`listen_port`。临时密钥签发同样可配置：`_key_issuer` 未注入时返回空映射（auth 关闭），注入时用 `self._ephemeral_key_ttl_sec` 作为 TTL 调 `issue_ephemeral_key`，失败抛 `EphemeralKeyIssueError` 并映射为 `SSH_KEY_ISSUE_FAILED`。外部 agent 的 SSH 私钥文件路径默认取 `DEFAULT_CLIENT_KEYS_DIR` 模板，经 `resolve_client_keys_dir(template, user_id)` 解析后拼接 `id_ed25519`。
+
+Sources / 来源：[jiuwenswarm/extensions/agentos/agentos_router/router_client.py:L1844–L1864](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/agentos/agentos_router/router_client.py#L1844-L1864), [jiuwenswarm/extensions/agentos/agentos_router/router_client.py:L2019–L2036](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/agentos/agentos_router/router_client.py#L2019-L2036), [jiuwenswarm/extensions/agentos/agentos_router/router_client.py:L1790–L1796](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/agentos/agentos_router/router_client.py#L1790-L1796)
+
+<!-- kb:knowledge owner=feature-thirdagent-list-switch facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**契约分层与 list/switch 数据流**
+
+契约分层：`ThirdAgent` 抽象（含 `normalize_agent_type`）下沉在 `jiuwenswarm/common/client/third_agent.py`，作为保留侧与 Gateway 仓共用的南北向契约；`jiuwenswarm/gateway/routing/third_agent.py` 仅 re-export 同一组符号以保持旧 import 路径兼容。运行时实现位于 `AgentOSRouterClient`：`thirdagent_list` 以 user_id 从 registry 的 `list_user_images` 取镜像，经 metadata（`name`/`agent_type`/`access_mode`）组装 `{agent_type, cmd}` 条目并附 `current_agent_type`；`thirdagent_switch` 依次校验 user_id、agent_type 规范化、北向 SSH 端点与临时密钥签发，然后或走 builtin 捷径（通过上述检查后仅记录 `_current_agent_types[uid]` 并返回 READY payload，不创建 sandbox），或经 `_agent_manager.get_or_create_agent` 复用/创建 runtime。当 `self._ssh_relay` 存在且实例确认不可用时，清理残留 runtime 后返回 `SSH_NOT_READY`；随后在 `_current_agent_types[uid]` 记录当前类型，成功 payload 合并 runtime info 与 `ssh_fields`/`key_fields`。
+
+Sources / 来源：[jiuwenswarm/common/client/third_agent.py:L3–L15](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/common/client/third_agent.py#L3-L15), [jiuwenswarm/gateway/routing/third_agent.py:L3–L17](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/routing/third_agent.py#L3-L17), [jiuwenswarm/extensions/agentos/agentos_router/router_client.py:L1817–L1842](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/agentos/agentos_router/router_client.py#L1817-L1842), [jiuwenswarm/extensions/agentos/agentos_router/router_client.py:L1910–L1929](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/extensions/agentos/agentos_router/router_client.py#L1910-L1929)
+
diff --git a/knowledge/repos/jiuwenswarm/components/gateway-channels/knowledge-gateway-channels.md b/knowledge/repos/jiuwenswarm/components/gateway-channels/knowledge-gateway-channels.md
new file mode 100644
index 00000000..385fb854
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/gateway-channels/knowledge-gateway-channels.md
@@ -0,0 +1,45 @@
+---
+title: "Gateway Web 频道处理器（channel_manager/web/app_web_handlers.py）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:.doc_project_maintainer/project/flows/gateway-agentserver-e2a-chat.md:L57-L63, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:.doc_project_maintainer/modules/gateway-and-channels/README.md:L36-L40, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L1915-L1932, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L2035-L2052, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L390-L399, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L2054-L2094, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L2104-L2128, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L2130-L2169, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L755-L792, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L1399-L1404, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L1425-L1428, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L1499-L1502]
+---
+
+# Gateway Web 频道处理器（channel_manager/web/app_web_handlers.py）
+
+<!-- kb:knowledge owner=gateway-channels facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证入口**
+
+Inference / 设计推断（非作者历史意图）：
+
+本文件源码内未展示针对这些处理器的直接测试。维护者文档称 E2A 聊天流程的验证存在于 `tests/unit_tests/agentserver/test_agentserver_modes.py`、`test_agent_ws_connection_close.py` 与 Gateway `test_agent_client.py`，并在 2026-08-03 记录 114 项生命周期测试通过；这些是文档声明而非本页可核验的运行结果，引用时需按 shown 源码复核。
+
+Sources / 来源：[.doc_project_maintainer/project/flows/gateway-agentserver-e2a-chat.md:L57–L63](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/.doc_project_maintainer/project/flows/gateway-agentserver-e2a-chat.md#L57-L63), [.doc_project_maintainer/modules/gateway-and-channels/README.md:L36–L40](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/.doc_project_maintainer/modules/gateway-and-channels/README.md#L36-L40)
+
+<!-- kb:knowledge owner=gateway-channels facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**职责与边界：Web RPC 处理器装配**
+
+该模块是 WebChannel 的 RPC 处理器与共享常量单一来源，核心入口 `_register_web_handlers(bind)` 通过 `WebHandlersBindParams` 装配 channel、agent_client、message_handler、channel_manager、updater_service 等依赖并注册 Web 前端所需 method。出站并非只走 message_handler：`_on_connect` 在有 message_handler 时经 `publish_robot_messages` 发 `connection.ack`，否则直接 `channel.send`（L2035–L2039）；`on_disconnect` 清理回调仅在 channel 暴露可调用的 `on_disconnect` 接口时注册（L2050–L2052）。另含 `_DummyBus`，仅满足 Channel 构造所需、不入队不路由（L390–L399）。
+
+Sources / 来源：[jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L1915–L1932](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py#L1915-L1932), [jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L2035–L2052](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py#L2035-L2052), [jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L390–L399](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py#L390-L399)
+
+<!-- kb:knowledge owner=gateway-channels facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**接口：委托与本地实现并存**
+
+`_register_web_handlers` 内注册的 RPC 中，`config.get`/`config.set`/`config.save_all` 委托给下沉的 `common.config_panel.config_set_handlers`（L2054–L2058、L2086–L2094），`models.list`/`models.replace_all`/模型校验委托给 `config_panel.models_handlers`（L2104–L2128）。但并非全部下沉：`_model_resource_rpc` 在本文件内本地实现 `models.get`、`models.references`、`models.delete`、`models.upsert` 等模型资源操作，经 `ModelCatalog`/`upsert_model_resource` 完成并统一用 `channel.send_response` 返回 ok/error/code（L2130–L2169）。
+
+Sources / 来源：[jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L2054–L2094](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py#L2054-L2094), [jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L2104–L2128](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py#L2104-L2128), [jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L2130–L2169](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py#L2130-L2169)
+
+<!-- kb:knowledge owner=gateway-channels facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**配置校验与多应用归一化**
+
+微信通道四个数值参数在 `channel.wechat.set_conf` 写盘前按 `_WECHAT_NUMERIC_BOUNDS` 校验范围（如 `long_poll_timeout_sec` 须为 1–600 的整数）；`backoff_max_sec` 不得小于 `backoff_base_sec` 的跨字段约束仅在两者同时出现在 params 时才检查（L755–L760、L789–L792）。飞书/小艺配置由 `_normalize_feishu_conf`/`_normalize_xiaoyi_conf` 统一为 apps 格式并按 `_FEISHU_APP_DEFAULTS`/`_XIAOYI_APP_DEFAULTS` 补齐缺省字段（L1425–L1428、L1499–L1502）；`_merge_apps_by_id` 以已有值为基座、新值覆盖做按 `app_id` 合并——注意归一化已先向新 app 填入默认空值，若前端提交了这些空值字段，仍会覆盖已有的 `app_secret`/`sk`，保护并非无条件成立（L1399–L1404）。
+
+Sources / 来源：[jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L755–L792](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py#L755-L792), [jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L1399–L1404](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py#L1399-L1404), [jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L1425–L1428](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py#L1425-L1428), [jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py:L1499–L1502](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py#L1499-L1502)
+
diff --git a/knowledge/repos/jiuwenswarm/components/gateway-channels/knowledge.md b/knowledge/repos/jiuwenswarm/components/gateway-channels/knowledge.md
new file mode 100644
index 00000000..9d23a866
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/gateway-channels/knowledge.md
@@ -0,0 +1,35 @@
+---
+title: "进程式 CLI 频道（process_cli）：REPL、worker 与会话操作"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:.doc_project_maintainer/project/flows/runtime-session-reference-chain.md:L66-L70, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:.doc_project_maintainer/modules/runtime-session/README.md:L42-L45, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/process_cli/repl.py:L371-L379, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/process_cli/repl.py:L407-L414, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/process_cli/repl.py:L484-L487, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/process_cli/commands.py:L75-L116, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/process_cli/repl.py:L228-L275, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/process_cli/repl.py:L297-L330, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/process_cli/repl.py:L738-L763, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/process_cli/live_layout.py:L23-L61]
+---
+
+# 进程式 CLI 频道（process_cli）：REPL、worker 与会话操作
+
+<!-- kb:knowledge owner=gateway-channels-2 facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证入口**
+
+维护者文档列出确定性 Runtime Session 测试与真实模型门禁：tests/system_tests/test_process_cli_session_runtime_live.py 覆盖 Work/Code 两轮恢复，以及 chat 与 Goal ask_user 首轮流结束后由回答恢复确切交互并得到终止响应；该文档自述 2026-09-10 全量受影响范围验证通过（四个配置模型门禁与 AgentServer/Gateway WebSocket 路由等）。代码内注释另指出 _run_worker 对无 stdout 读取器的“轻量进程替身”做了兼容，说明存在依赖该替身的频道生命周期测试。以上均为文档与代码可见证据，本轮输入未运行任何测试。
+
+Sources / 来源：[.doc_project_maintainer/project/flows/runtime-session-reference-chain.md:L66–L70](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/.doc_project_maintainer/project/flows/runtime-session-reference-chain.md#L66-L70), [.doc_project_maintainer/modules/runtime-session/README.md:L42–L45](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/.doc_project_maintainer/modules/runtime-session/README.md#L42-L45), [jiuwenswarm/channels/process_cli/repl.py:L371–L379](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/process_cli/repl.py#L371-L379)
+
+<!-- kb:knowledge owner=gateway-channels-2 facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**入口与结果契约**
+
+公开入口是 repl.run_repl(args) -> int，内部循环读取提示词并分发。_run_worker 返回 (return_code, next_session)：worker 退出码非 0/130 时向 stderr 输出含日志尾部的诊断；130（用户中断）由 repl.py 中 cancel_requested 或 CancelledError 分支赋值，app.run 遇到 CancelledError 则渲染中断事件后重新抛出而非返回 130。本地命令注册表由 commands.py 的 SLASH_COMMANDS 提供，parse_slash_command 把名称规范化为不带参数解释的 ParsedSlashCommand。
+
+Sources / 来源：[jiuwenswarm/channels/process_cli/repl.py:L407–L414](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/process_cli/repl.py#L407-L414), [jiuwenswarm/channels/process_cli/repl.py:L484–L487](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/process_cli/repl.py#L484-L487), [jiuwenswarm/channels/process_cli/commands.py:L75–L116](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/process_cli/commands.py#L75-L116)
+
+<!-- kb:knowledge owner=gateway-channels-2 facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**会话操作与运行中输入**
+
+REPL 支持会话 create/switch（/resume、别名 /continue）/fork（/branch、别名 /fork）/delete：/delete 需交互确认，成功删除当前会话后清空 state.session_id；/sessions 打开分页浏览（n/p 翻页、s 搜索、序号选择）。chat 运行期间父进程把非斜杠输入作为补充转发到 worker stdin，并用 LiveTurnLayout 在单一 prompt 应用中展示请求、补充（含回执标记）、通知与模型输出；/cancel 通过 SIGINT（Windows 为 CTRL_BREAK_EVENT）→ terminate → kill 的梯度中断 worker。
+
+Sources / 来源：[jiuwenswarm/channels/process_cli/repl.py:L228–L275](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/process_cli/repl.py#L228-L275), [jiuwenswarm/channels/process_cli/repl.py:L297–L330](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/process_cli/repl.py#L297-L330), [jiuwenswarm/channels/process_cli/repl.py:L738–L763](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/process_cli/repl.py#L738-L763), [jiuwenswarm/channels/process_cli/live_layout.py:L23–L61](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/process_cli/live_layout.py#L23-L61)
+
diff --git a/knowledge/repos/jiuwenswarm/components/gateway-channels/scripts/_index.md b/knowledge/repos/jiuwenswarm/components/gateway-channels/scripts/_index.md
new file mode 100644
index 00000000..692bba20
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/gateway-channels/scripts/_index.md
@@ -0,0 +1,13 @@
+---
+title: "scripts"
+created: 2026-10-06
+updated: 2026-10-06
+type: index
+tags: [jiuwenswarm]
+sources: []
+---
+
+# scripts
+
+理解本目录对应源码 owner 的职责、接口与集成边界时查这里。源码接口记录说明静态声明；完整功能语义、配置和设计取舍沿下面的功能页查证。通用审查方法不放在这里。
+- [scripts 源码接口与集成边界 01](source-contracts-01.md)
diff --git a/knowledge/repos/jiuwenswarm/components/gateway-channels/scripts/source-contracts-01.md b/knowledge/repos/jiuwenswarm/components/gateway-channels/scripts/source-contracts-01.md
new file mode 100644
index 00000000..ee6f6679
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/gateway-channels/scripts/source-contracts-01.md
@@ -0,0 +1,21 @@
+---
+title: "scripts 源码接口与集成边界 01"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: []
+---
+
+# scripts 源码接口与集成边界 01
+
+本页逐文件说明这一源码模块声明的接口、类型与依赖。记录来自静态源码声明，不证明控制流、配置生效、外部服务可用或测试通过；功能语义与设计取舍沿上级功能页继续阅读。
+
+<!-- kb:file path=jiuwenswarm/scripts/whatsapp-bridge.js pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b sha256=dfa7ae64443b13a401f3eb99344c561974f8720ce5c43f37a319049b15f9e66f -->
+**`jiuwenswarm/scripts/whatsapp-bridge.js`**
+
+- 源码声明的类型、组件或调用边界：`fs`, `path`, `pino`, `qrcodeTerminal`, `loadBaileys`, `makeWASocket`, `useMultiFileAuthState`, `DisconnectReason`；这是词法声明索引，不把局部变量当成对外导出 API。
+- 集成边界的导入/加载声明：`const fs = require("fs");`；`const path = require("path");`；`const { WebSocketServer } = require("ws");`；`const pino = require("pino");`。
+
+源码依据：[完整声明与实现](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/scripts/whatsapp-bridge.js#L1-L281)。
+<!-- /kb:file -->
diff --git a/knowledge/repos/jiuwenswarm/components/ide-clients/_index.md b/knowledge/repos/jiuwenswarm/components/ide-clients/_index.md
index a0825dd0..4fb8e5b2 100644
--- a/knowledge/repos/jiuwenswarm/components/ide-clients/_index.md
+++ b/knowledge/repos/jiuwenswarm/components/ide-clients/_index.md
@@ -27,3 +27,8 @@ sources: []
 | PR 描述在做什么 | 精确规则 | 第一批 live 源码 |
 |---|---|---|
 | ide clients | 入口 | `jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/JiuwenSwarmService.kt`、`jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/ChatToolWindow.kt`、`jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffApplier.ts` |
+
+- [JetBrains 插件（ide-clients）：架构、API、配置与行为](knowledge.md)
+- [IDE 端代理文件编辑直接应用（DiffApplier）](feature-ide-file-edit-diff-apply.md)
+- [IDE 单轮文件快照与回退（Rewind）](feature-ide-turn-rewind-snapshot.md)
+- [shared-webview](shared-webview/_index.md)
diff --git a/knowledge/repos/jiuwenswarm/components/ide-clients/feature-ide-file-edit-diff-apply.md b/knowledge/repos/jiuwenswarm/components/ide-clients/feature-ide-file-edit-diff-apply.md
new file mode 100644
index 00000000..76b2a980
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/ide-clients/feature-ide-file-edit-diff-apply.md
@@ -0,0 +1,54 @@
+---
+title: "IDE 端代理文件编辑直接应用（DiffApplier）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffApplier.ts:L70-L84, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffApplier.ts:L27-L48, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/editor/DiffApplier.kt:L44-L56, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffApplier.ts:L85-L123, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffApplier.ts:L148-L164, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffApplier.ts:L273-L286, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffApplier.ts:L288-L294, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L368-L396, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffApplier.ts:L5-L16, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L355-L404, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L464-L471, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffApplier.ts:L81-L84, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L368-L404, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/editor/DiffApplier.kt:L70-L78]
+feature: "ide-file-edit-diff-apply"
+entry_points: ["jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/ChatToolWindow.kt", "jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffApplier.ts"]
+source_globs: ["jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/ChatToolWindow.kt", "jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffApplier.ts", "jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/editor/DiffApplier.kt", "jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts"]
+---
+
+# IDE 端代理文件编辑直接应用（DiffApplier）
+
+<!-- kb:knowledge owner=feature-ide-file-edit-diff-apply facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**公开入口与生命周期**
+
+VS Code 版 `DiffApplier.ts` 的主入口是 `handleToolCall(event)`：解析 `chat.tool_call` 事件负载，若 tool_name 属于 EDIT_TOOLS（str_replace_editor / write_file / create_file / edit_file）则应用编辑并返回布尔值表示是否已处理。配套导出快照生命周期函数：`ensureSnapshot`、`clearSnapshots`、`promoteSnapshots`（chat.final 时调用）、`getLastTurnSnapshots`、`clearLastTurnSnapshots`，以及 `performRewind(snapshots)` 返回 `{restored, failed}`。JetBrains 版入口是 `DiffApplier.handle(project, event)`，非 EDT 线程调用时通过 `invokeAndWait` 跳转到 EDT 再分发到各工具处理函数。
+
+Sources / 来源：[jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffApplier.ts:L70–L84](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffApplier.ts#L70-L84), [jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffApplier.ts:L27–L48](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffApplier.ts#L27-L48), [jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/editor/DiffApplier.kt:L44–L56](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/editor/DiffApplier.kt#L44-L56)
+
+<!-- kb:knowledge owner=feature-ide-file-edit-diff-apply facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的编辑行为**
+
+支持四类工具调用：`str_replace_editor`（command 为 str_replace 或 create，参数 path/old_str/new_str 或 file_text）、`edit_file`（ACP 风格 file_path + old_string/new_string）、`write_file`/`create_file`（整文件 path+content）。字符串替换通过 `indexOf(oldStr)` 定位后拼接新文本；找不到目标文本或文件不存在时弹出错误通知并返回 false。写入新文件时会递归创建父目录。参数 arguments 既可为对象也可为 JSON 字符串（`parseArguments` 兼容两种）。配合快照机制提供按回合的 rewind（回滚到本回合首次编辑前的内容，含删除新建文件）。
+
+Sources / 来源：[jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffApplier.ts:L85–L123](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffApplier.ts#L85-L123), [jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffApplier.ts:L148–L164](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffApplier.ts#L148-L164), [jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffApplier.ts:L273–L286](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffApplier.ts#L273-L286)
+
+<!-- kb:knowledge owner=feature-ide-file-edit-diff-apply facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证入口**
+
+所示文件片段中未包含针对 DiffApplier 的测试代码；可观察的验证途径是运行时的 `notify()` 通知（VS Code 版 showInformationMessage/showErrorMessage，JetBrains 版 NotificationGroup "JiuwenSwarm"）以及 ChatPanel 的 debug 日志（如 `SNAP →`、`DIFF → accepted/rejected`、`REWIND→`），用于人工确认快照、diff 接受与回滚行为。本组输入不足以判断仓库中是否存在自动化测试。
+
+Sources / 来源：[jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffApplier.ts:L288–L294](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffApplier.ts#L288-L294), [jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L368–L396](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts#L368-L396)
+
+<!-- kb:knowledge owner=feature-ide-file-edit-diff-apply facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**职责与数据流**
+
+DiffApplier 拦截 `chat.tool_call` 事件中的代理文件编辑工具调用（str_replace_editor / write_file / create_file / edit_file）并应用到 IDE 工作区，同时维护编辑前快照供 rewind 使用。VS Code 端由 ChatPanel 驱动：解析事件后，若 `useDiffViewer` 开启则先计算提议内容并弹 diff（L388-L395：被拒绝时跳过 `handleToolCall`，事件仍转发给 webview；L397-L399：无法计算提议内容时回退为直接应用），否则直接调用 `DiffApplier.handleToolCall`；`chat.final` 时调用 `promoteSnapshots()`，仅当其返回 true（即本回合有快照）才向 webview 发送 `rewindable`。JetBrains 端入口 `DiffApplier.handle(project, event)` 强制在 EDT 上执行（非 EDT 时 `invokeAndWait` 跳转），按 `autoApply` 决定写入还是仅显示 diff 对话框。
+
+Sources / 来源：[jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffApplier.ts:L5–L16](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffApplier.ts#L5-L16), [jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L355–L404](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts#L355-L404), [jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L464–L471](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts#L464-L471), [jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/editor/DiffApplier.kt:L44–L56](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/editor/DiffApplier.kt#L44-L56)
+
+<!-- kb:knowledge owner=feature-ide-file-edit-diff-apply facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**配置项与读取方式**
+
+VS Code 端通过 `vscode.workspace.getConfiguration('jiuwenswarm')` 读取三项设置：`approveEdits`（默认 false，为 true 时每次编辑前弹 Approve/Reject 对话框，在 DiffApplier 内读取）、`rewindEnabled`（默认 true，控制 ChatPanel 是否在工具调用前预先 `ensureSnapshot`）与 `useDiffViewer`（默认 false，为 true 时先计算提议内容并弹原生 diff，被拒绝则不调用 `handleToolCall`，无法计算提议内容时回退直接应用）。JetBrains 端从 `JiuwenSwarmSettings.instance()` 读取 `autoApplyEdits` 与 `approveEdits`：autoApply 为 true 时直接写入，否则仅显示 diff 对话框；该设置类的定义未在所示片段中给出。
+
+Sources / 来源：[jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffApplier.ts:L81–L84](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffApplier.ts#L81-L84), [jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L368–L404](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts#L368-L404), [jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/editor/DiffApplier.kt:L70–L78](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/editor/DiffApplier.kt#L70-L78)
+
diff --git a/knowledge/repos/jiuwenswarm/components/ide-clients/feature-ide-turn-rewind-snapshot.md b/knowledge/repos/jiuwenswarm/components/ide-clients/feature-ide-turn-rewind-snapshot.md
new file mode 100644
index 00000000..61410961
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/ide-clients/feature-ide-turn-rewind-snapshot.md
@@ -0,0 +1,46 @@
+---
+title: "IDE 单轮文件快照与回退（Rewind）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/ChatToolWindow.kt:L627-L630, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/settings/JiuwenSwarmSettings.kt:L30-L34, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/ChatToolWindow.kt:L503-L512, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/ChatToolWindow.kt:L641-L649, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/ChatToolWindow.kt:L622-L650, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/ChatToolWindow.kt:L494-L502, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/ChatToolWindow.kt:L315-L318, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/ChatToolWindow.kt:L113-L117, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/ChatToolWindow.kt:L486-L512, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffApplier.ts:L26-L64]
+feature: "ide-turn-rewind-snapshot"
+entry_points: ["jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/ChatToolWindow.kt", "jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffApplier.ts"]
+source_globs: ["jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/ChatToolWindow.kt", "jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffApplier.ts", "jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/settings/JiuwenSwarmSettings.kt"]
+---
+
+# IDE 单轮文件快照与回退（Rewind）
+
+<!-- kb:knowledge owner=feature-ide-turn-rewind-snapshot facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**rewindEnabled 开关**
+
+快照采集受 `JiuwenSwarmSettings.instance().rewindEnabled` 布尔设置门控，仅在该设置为 true 且工具属于 `str_replace_editor`/`write_file`/`create_file`/`edit_file` 时才采集。所示 JiuwenSwarmSettings.kt 行段（30-34）未包含 rewindEnabled 的定义与默认值，默认行为无法从所示证据确认。
+
+Sources / 来源：[jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/ChatToolWindow.kt:L627–L630](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/ChatToolWindow.kt#L627-L630), [jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/settings/JiuwenSwarmSettings.kt:L30–L34](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/settings/JiuwenSwarmSettings.kt#L30-L34)
+
+<!-- kb:knowledge owner=feature-ide-turn-rewind-snapshot facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证**
+
+所示证据中未包含针对快照/回退的自动化测试；可观察的验证途径是运行期 debug 日志（"SNAP → snapshotted …"、"Rewind failed for …"）和 webview 收到的 `rewind_done` 计数消息。
+
+Sources / 来源：[jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/ChatToolWindow.kt:L503–L512](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/ChatToolWindow.kt#L503-L512), [jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/ChatToolWindow.kt:L641–L649](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/ChatToolWindow.kt#L641-L649)
+
+<!-- kb:knowledge owner=feature-ide-turn-rewind-snapshot facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**采集、晋升与生命周期**
+
+快照采集发生在 `chat.tool_call`/`chat.tool_update` 事件处理中：仅当 `JiuwenSwarmSettings.instance().rewindEnabled` 为 true 且工具名为 `str_replace_editor`/`write_file`/`create_file`/`edit_file` 时，从 arguments 的 `file_path`/`path` 取路径，对该路径首次出现时在 ReadAction 中读入原内容（文件不存在或读取抛异常时记 null）。恢复路径上，null 快照且文件存在时删除文件；非 null 快照仅当 VFS 中仍能找到该文件（`vf != null`）时才用 `setBinaryContent` 写回。用户发送新消息（"send"）时清空 current/last 快照并通知 webview `rewindable=false`；代码注释声明 chat.final 时将 current 晋升为 last，但该晋升的执行代码不在所示片段内。
+
+Sources / 来源：[jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/ChatToolWindow.kt:L622–L650](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/ChatToolWindow.kt#L622-L650), [jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/ChatToolWindow.kt:L494–L502](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/ChatToolWindow.kt#L494-L502), [jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/ChatToolWindow.kt:L315–L318](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/ChatToolWindow.kt#L315-L318), [jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/ChatToolWindow.kt:L113–L117](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/ChatToolWindow.kt#L113-L117)
+
+<!-- kb:knowledge owner=feature-ide-turn-rewind-snapshot facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**入口与生命周期**
+
+JetBrains 侧入口是 ChatToolWindow 的 webview 消息处理分支：消息的 type 字段等于字符串 "rewind" 时触发回退；若无快照（lastTurnSnapshots 为空）直接返回，否则在 pooled 线程中对每个文件执行一次 WriteCommandAction（名称 "Rewind agent changes"），完成后向 webview 发送含 restored/failed 计数的 rewind_done 消息。VS Code 侧 DiffApplier.ts 导出模块级快照 API：clearSnapshots()（清空当前与上一轮）、promoteSnapshots()（chat.final 时晋升并返回是否有可回退文件）、getLastTurnSnapshots()（返回副本）、clearLastTurnSnapshots() 和 ensureSnapshot(filePath)（本轮首次出现的路径才采集）。
+
+Sources / 来源：[jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/ChatToolWindow.kt:L486–L512](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/ChatToolWindow.kt#L486-L512), [jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffApplier.ts:L26–L64](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffApplier.ts#L26-L64)
+
diff --git a/knowledge/repos/jiuwenswarm/components/ide-clients/feature-jetbrains.md b/knowledge/repos/jiuwenswarm/components/ide-clients/feature-jetbrains.md
index 9bcf395e..e93ec050 100644
--- a/knowledge/repos/jiuwenswarm/components/ide-clients/feature-jetbrains.md
+++ b/knowledge/repos/jiuwenswarm/components/ide-clients/feature-jetbrains.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/ide/jetbrains/JetBrains插件.md
 feature: "jetbrains"
 entry_points: ["jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/JiuwenSwarmService.kt"]
-source_globs: ["jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/JiuwenSwarmService.kt", "jiuwenswarm/channels/ide/packages/jetbrains-plugin/*"]
+source_globs: ["jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/JiuwenSwarmService.kt", "jiuwenswarm/channels/ide/packages/jetbrains-plugin/*", "jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/context/ContextCollector.kt", "jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/Actions.kt", "jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/context/GitContextProvider.kt", "jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/ChatToolWindow.kt", "jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/FixWithAiIntention.kt", "jiuwenswarm/channels/ide/packages/vscode-extension/src/codeActions/FixWithAiCodeActionProvider.ts", "jiuwenswarm/channels/ide/packages/jetbrains-plugin/build.gradle.kts", "jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/settings/JiuwenSwarmSettings.kt", "jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/settings/SettingsConfigurable.kt", "jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/client/SessionManager.kt", "jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/StatusBarWidgetFactory.kt", "jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/client/WsClient.kt"]
 ---
 
 # JetBrains 客户端 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/ide-clients/feature-vscode.md b/knowledge/repos/jiuwenswarm/components/ide-clients/feature-vscode.md
index 759179af..0967c511 100644
--- a/knowledge/repos/jiuwenswarm/components/ide-clients/feature-vscode.md
+++ b/knowledge/repos/jiuwenswarm/components/ide-clients/feature-vscode.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/ide/vscode/VSCode插件.md
 feature: "vscode"
 entry_points: ["jiuwenswarm/channels/ide/packages/vscode-extension/src/extension.ts"]
-source_globs: ["jiuwenswarm/channels/ide/packages/vscode-extension/src/extension.ts", "jiuwenswarm/channels/ide/packages/vscode-extension/*"]
+source_globs: ["jiuwenswarm/channels/ide/packages/vscode-extension/src/extension.ts", "jiuwenswarm/channels/ide/packages/vscode-extension/*", "jiuwenswarm/channels/ide/packages/shared-webview/chat.html", "jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts", "jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/StatusBar.ts", "jiuwenswarm/channels/ide/packages/vscode-extension/src/client/protocol.ts", "jiuwenswarm/channels/ide/packages/vscode-extension/src/client/WsClient.ts", "jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/ui/SwarmMapPanel.kt", "jiuwenswarm/channels/ide/packages/vscode-extension/esbuild.js", "jiuwenswarm/channels/ide/packages/vscode-extension/src/editor/DiffViewer.ts", "jiuwenswarm/channels/browser/frontend/src/webview/chat.html"]
 ---
 
 # VS Code 客户端 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/ide-clients/knowledge.md b/knowledge/repos/jiuwenswarm/components/ide-clients/knowledge.md
new file mode 100644
index 00000000..809c1e56
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/ide-clients/knowledge.md
@@ -0,0 +1,61 @@
+---
+title: "JetBrains 插件（ide-clients）：架构、API、配置与行为"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/JiuwenSwarmService.kt:L15-L30, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/client/WsClient.kt:L130-L138, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/client/SessionManager.kt:L275-L337, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/settings/JiuwenSwarmSettings.kt:L8-L40, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/settings/JiuwenSwarmSettings.kt:L110-L120, "openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/ide/jetbrains/JetBrains插件.md:L15-L30", "openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/ide/jetbrains/JetBrains插件.md:L96-L108", openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/client/SessionManager.kt:L240-L273, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/client/SessionManager.kt:L159-L167, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/client/SessionManager.kt:L222-L231, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/context/GitContextProvider.kt:L8-L16, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/context/GitContextProvider.kt:L51-L63, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/client/WsClient.kt:L29-L32, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/context/ContextCollector.kt:L27-L48, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/client/SessionManager.kt:L166-L190, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/editor/DiffApplier.kt:L27-L38, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/editor/DiffApplier.kt:L184-L215]
+---
+
+# JetBrains 插件（ide-clients）：架构、API、配置与行为
+
+<!-- kb:knowledge owner=ide-clients facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**应用级单例组合 WsClient 与 SessionManager**
+
+JiuwenSwarmService 是注册为 applicationService 的应用级单例（实现 Disposable），构造时从 JiuwenSwarmSettings 读取 wsUrl 与保活参数创建 WsClient，再把 ws 与 channelId 交给 SessionManager；dispose 时依次关闭重试线程、session 与 ws。数据流为：WsClient 解析 JSON 消息后广播给 message 监听者，SessionManager 消费 res/event 完成请求 Future 与 connection.ack 会话建立，DiffApplier/ContextCollector/SwarmStateManager 处理各自的工具调用、上下文与团队事件。
+
+Sources / 来源：[jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/JiuwenSwarmService.kt:L15–L30](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/JiuwenSwarmService.kt#L15-L30), [jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/client/WsClient.kt:L130–L138](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/client/WsClient.kt#L130-L138), [jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/client/SessionManager.kt:L275–L337](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/client/SessionManager.kt#L275-L337)
+
+<!-- kb:knowledge owner=ide-clients facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**JiuwenSwarmSettings：持久化状态与 ws/wss 判定**
+
+设置以 PersistentStateComponent 存于 jiuwenswarm.xml，默认 host=127.0.0.1、port=19000、channelId="ide"、defaultMode="code.plan"、autoConnect=true、keepAliveInterval=30（写入时钳制 5–300）、projectTreeMaxFiles=200（10–2000）、autoApplyEdits/approveEdits/gitEnabled 默认关闭。wsUrl 按 host 是否为本机（空/127.0.0.1/localhost/::1）选择 ws 或 wss，路径固定 /ws；文档设置表与这些默认值一致。
+
+Sources / 来源：[jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/settings/JiuwenSwarmSettings.kt:L8–L40](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/settings/JiuwenSwarmSettings.kt#L8-L40), [jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/settings/JiuwenSwarmSettings.kt:L110–L120](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/settings/JiuwenSwarmSettings.kt#L110-L120), [docs/zh/ide/jetbrains/JetBrains插件.md:L15–L30](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/docs/zh/ide/jetbrains/JetBrains%E6%8F%92%E4%BB%B6.md#L15-L30)
+
+<!-- kb:knowledge owner=ide-clients facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**文档化的手动验收路径**
+
+本批输入未包含插件自身的自动化测试；docs/zh/ide/jetbrains/JetBrains插件.md 记录了手动验收预期：编辑工具被插件拦截，默认打开并排 diff 窗口（关闭即应用），自动应用模式经 WriteCommandAction 写入且可 Ctrl+Z 撤销，要求批准模式在 diff 或应用前弹确认；shell 命令在专用 JiuwenSwarm 终端标签页中运行并复用。这些是文档声明，本轮未对照运行验证。
+
+Sources / 来源：[docs/zh/ide/jetbrains/JetBrains插件.md:L96–L108](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/docs/zh/ide/jetbrains/JetBrains%E6%8F%92%E4%BB%B6.md#L96-L108)
+
+<!-- kb:knowledge owner=ide-clients facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**SessionManager request/send contracts**
+
+The private request(method, params, sid) builds a `type:"req"` message, registers a CompletableFuture keyed by UUID, and blocks up to 5 seconds (REQUEST_TIMEOUT_SEC); it fail-fasts with `check(!isDispatchThread)` so callers must run off the EDT, and throws IllegalStateException if ws.send fails. sendChat returns false without sending when sessionId is null; interrupt() sends `chat.interrupt` fire-and-forget and discards the ws.send result (no Boolean return).
+
+Sources / 来源：[jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/client/SessionManager.kt:L240–L273](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/client/SessionManager.kt#L240-L273), [jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/client/SessionManager.kt:L159–L167](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/client/SessionManager.kt#L159-L167), [jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/client/SessionManager.kt:L222–L231](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/client/SessionManager.kt#L222-L231)
+
+<!-- kb:knowledge owner=ide-clients facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**Subprocess git and forced IPv4**
+
+Inference / 设计推断（非作者历史意图）：
+
+GitContextProvider shells out to `git` instead of git4idea to keep a single-module, dependency-free plugin that works across JetBrains IDEs (per its doc comment); the cost is that runGit reads stdout to EOF before the 5-second waitFor, so a hung git process can block collection rather than hitting the timeout. WsClient unconditionally rewrites `://localhost:` to `://127.0.0.1:` (inference: avoids macOS IPv6-first resolution failures at the cost of unreachable IPv6-only local servers).
+
+Sources / 来源：[jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/context/GitContextProvider.kt:L8–L16](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/context/GitContextProvider.kt#L8-L16), [jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/context/GitContextProvider.kt:L51–L63](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/context/GitContextProvider.kt#L51-L63), [jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/client/WsClient.kt:L29–L32](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/client/WsClient.kt#L29-L32)
+
+<!-- kb:knowledge owner=ide-clients facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**自动 IDE 上下文注入与代理文件编辑拦截**
+
+ContextCollector.collect 汇集活动文件/光标/选区/诊断、其他打开标签、可选项目树、git 子进程摘要、项目规则与 @提及文件，组成 `<!-- IDE Context -->` 结构块；sendChat 将该块拼接在用户 content 之后（"$content\n\n$ideContext"）随 chat.send 发送，还可携带图片 media_items 与 model_name。DiffApplier 拦截 str_replace_editor / edit_file / write_file / create_file 的工具调用事件：默认弹出并排 diff（当前 vs 拟议），autoApplyEdits 开启时经 WriteCommandAction 直接写入，approveEdits 开启时先弹确认对话框。
+
+Sources / 来源：[jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/context/ContextCollector.kt:L27–L48](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/context/ContextCollector.kt#L27-L48), [jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/client/SessionManager.kt:L166–L190](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/client/SessionManager.kt#L166-L190), [jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/editor/DiffApplier.kt:L27–L38](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/editor/DiffApplier.kt#L27-L38), [jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/editor/DiffApplier.kt:L184–L215](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/editor/DiffApplier.kt#L184-L215)
+
diff --git a/knowledge/repos/jiuwenswarm/components/ide-clients/shared-webview/_index.md b/knowledge/repos/jiuwenswarm/components/ide-clients/shared-webview/_index.md
new file mode 100644
index 00000000..8c9ec604
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/ide-clients/shared-webview/_index.md
@@ -0,0 +1,13 @@
+---
+title: "shared-webview"
+created: 2026-10-06
+updated: 2026-10-06
+type: index
+tags: [jiuwenswarm]
+sources: []
+---
+
+# shared-webview
+
+理解本目录对应源码 owner 的职责、接口与集成边界时查这里。源码接口记录说明静态声明；完整功能语义、配置和设计取舍沿下面的功能页查证。通用审查方法不放在这里。
+- [shared-webview 源码接口与集成边界 01](source-contracts-01.md)
diff --git a/knowledge/repos/jiuwenswarm/components/ide-clients/shared-webview/source-contracts-01.md b/knowledge/repos/jiuwenswarm/components/ide-clients/shared-webview/source-contracts-01.md
new file mode 100644
index 00000000..f5c0428f
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/ide-clients/shared-webview/source-contracts-01.md
@@ -0,0 +1,21 @@
+---
+title: "shared-webview 源码接口与集成边界 01"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: []
+---
+
+# shared-webview 源码接口与集成边界 01
+
+本页逐文件说明这一源码模块声明的接口、类型与依赖。记录来自静态源码声明，不证明控制流、配置生效、外部服务可用或测试通过；功能语义与设计取舍沿上级功能页继续阅读。
+
+<!-- kb:file path=jiuwenswarm/channels/ide/packages/shared-webview/swarm_map.html pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b sha256=850561d890e4584a7319a9322601c85c60834097d056000aa1fcfc39c66a6495 -->
+**`jiuwenswarm/channels/ide/packages/shared-webview/swarm_map.html`**
+
+- 源码声明的类型、组件或调用边界：`IDLE_WARN_MS`, `FEED_MAX`, `LANE_COLOURS`, `_laneColourMap`, `ORCHESTRATOR_NAME`, `_state`, `_msgOpen`, `_debugOpen`；这是词法声明索引，不把局部变量当成对外导出 API。
+- 页面装配边界：body, script 标签；资源装载与宿主连接取决于对应属性和脚本实现。
+
+源码依据：[完整声明与实现](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/shared-webview/swarm_map.html#L1-L1693)。
+<!-- /kb:file -->
diff --git a/knowledge/repos/jiuwenswarm/components/ide-vscode/_index.md b/knowledge/repos/jiuwenswarm/components/ide-vscode/_index.md
index 49e96be1..73d43dba 100644
--- a/knowledge/repos/jiuwenswarm/components/ide-vscode/_index.md
+++ b/knowledge/repos/jiuwenswarm/components/ide-vscode/_index.md
@@ -19,3 +19,6 @@ sources: []
 | PR 描述在做什么 | 精确规则 | 第一批 live 源码 |
 |---|---|---|
 | ide vscode | 入口 | `jiuwenswarm/channels/ide/packages/vscode-extension/src/terminal/TerminalManager.ts`、`jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts` |
+
+- [ide-vscode：VS Code 聊天面板与终端命令镜像](knowledge.md)
+- [IDE 终端命令镜像执行（VS Code 扩展与 JetBrains 插件）](feature-ide-terminal-command-mirror.md)
diff --git a/knowledge/repos/jiuwenswarm/components/ide-vscode/feature-ide-terminal-command-mirror.md b/knowledge/repos/jiuwenswarm/components/ide-vscode/feature-ide-terminal-command-mirror.md
new file mode 100644
index 00000000..1697672d
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/ide-vscode/feature-ide-terminal-command-mirror.md
@@ -0,0 +1,32 @@
+---
+title: "IDE 终端命令镜像执行（VS Code 扩展与 JetBrains 插件）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/vscode-extension/src/terminal/TerminalManager.ts:L5-L18, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/terminal/TerminalManager.kt:L49-L61, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L408-L418]
+feature: "ide-terminal-command-mirror"
+entry_points: ["jiuwenswarm/channels/ide/packages/vscode-extension/src/terminal/TerminalManager.ts", "jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts"]
+source_globs: ["jiuwenswarm/channels/ide/packages/vscode-extension/src/terminal/TerminalManager.ts", "jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts", "jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/terminal/TerminalManager.kt"]
+---
+
+# IDE 终端命令镜像执行（VS Code 扩展与 JetBrains 插件）
+
+<!-- kb:knowledge owner=feature-ide-terminal-command-mirror facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的镜像行为与终端复用**
+
+功能将 agent 的 `bash`/`run_command` 工具调用镜像到用户可见的 IDE 终端，展示实时输出。VS Code 端按会话复用单个名为 JiuwenSwarm 的终端，首次命令时惰性创建，每次执行前 `show()` 前置；JetBrains 端同样按终端标题 "JiuwenSwarm" 查找既有 widget，不存在时调用 `createLocalShellWidget(project.basePath, "JiuwenSwarm")` 新建，执行后把 Terminal 工具窗口带到前台。
+
+Sources / 来源：[jiuwenswarm/channels/ide/packages/vscode-extension/src/terminal/TerminalManager.ts:L5–L18](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/vscode-extension/src/terminal/TerminalManager.ts#L5-L18), [jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/terminal/TerminalManager.kt:L49–L61](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/jetbrains-plugin/src/main/kotlin/com/jiuwenswarm/plugin/terminal/TerminalManager.kt#L49-L61)
+
+<!-- kb:knowledge owner=feature-ide-terminal-command-mirror facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证**
+
+Inference / 设计推断（非作者历史意图）：
+
+所示文件片段中未包含针对 TerminalManager 或命令镜像路径的测试代码；ChatPanel 中的 `this.debug(\`TERM  → ${cmd}\`)` 调试日志是运行时确认命令提取与镜像触发点的可观测入口。无法据此判断仓库其他位置是否存在相关测试。
+
+Sources / 来源：[jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L408–L418](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts#L408-L418)
+
diff --git a/knowledge/repos/jiuwenswarm/components/ide-vscode/knowledge.md b/knowledge/repos/jiuwenswarm/components/ide-vscode/knowledge.md
new file mode 100644
index 00000000..2a904b30
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/ide-vscode/knowledge.md
@@ -0,0 +1,51 @@
+---
+title: "ide-vscode：VS Code 聊天面板与终端命令镜像"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L46-L60, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L321-L343, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/vscode-extension/src/terminal/TerminalManager.ts:L1-L17, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L355-L418, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L929-L940, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L1053-L1081, "openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/ide/vscode/VSCode插件.md:L1-L2", openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/vscode-extension/src/terminal/TerminalManager.ts:L9-L28, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/vscode-extension/src/terminal/TerminalManager.ts:L34-L48, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L63-L112, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L369-L404, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L548-L557, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L657-L674, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L949-L965, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L199-L203, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L1003-L1008]
+---
+
+# ide-vscode：VS Code 聊天面板与终端命令镜像
+
+<!-- kb:knowledge owner=ide-vscode facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**ChatPanel 作为扩展宿主中的消息枢纽**
+
+ChatPanel 是 VS Code 扩展侧的核心编排者：构造时订阅 WsClient 的 status/message 事件与 SessionManager 的会话变更，把服务端消息转换后转发给 webview，并在 dispose 时统一解绑。它还拥有 SwarmStateManager 与 SwarmMapPanel，服务端的 team.* 事件在 onJiuwenMessage 中被先行拦截（不转发给 webview），用于驱动 Swarm Map 的泳道状态。TerminalManager 则是模块级单例，持有唯一的 activeTerminal。
+
+Sources / 来源：[jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L46–L60](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts#L46-L60), [jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L321–L343](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts#L321-L343), [jiuwenswarm/channels/ide/packages/vscode-extension/src/terminal/TerminalManager.ts:L1–L17](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/vscode-extension/src/terminal/TerminalManager.ts#L1-L17)
+
+<!-- kb:knowledge owner=ide-vscode facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**文件编辑拦截、终端镜像与 Git/内存辅助功能**
+
+onJiuwenMessage 拦截 str_replace_editor/write_file/create_file/edit_file 工具调用，按配置快照（rewindEnabled）并在 chat.final 时提升快照、显示回退条，用户发送下一条消息前可整体回退该轮修改；bash/run_command 则按 runCommandsInTerminal 镜像执行。此外 ChatPanel 每 10 秒轮询 session.getMemoryUsage() 推送给 webview，启用 gitEnabled 时通过 execSync 调 git 子进程实现状态展示与提交/推送快捷操作。JetBrains 文档描述了同构的终端集成与检查点/回退行为，VS Code 专属文档（VSCode插件.md）在所示片段中仅有标题，内容为空。
+
+Sources / 来源：[jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L355–L418](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts#L355-L418), [jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L929–L940](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts#L929-L940), [jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L1053–L1081](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts#L1053-L1081), [docs/zh/ide/vscode/VSCode插件.md:L1–L2](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/docs/zh/ide/vscode/VSCode%E6%8F%92%E4%BB%B6.md#L1-L2)
+
+<!-- kb:knowledge owner=ide-vscode facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**公开入口与生命周期**
+
+TerminalManager 是模块级单例，导出三个函数：runCommand(command, cwd?) 惰性创建名为 JiuwenSwarm 的终端并 sendText；disposeTerminal() 容错释放并置空引用；extractCommand(payload) 从多种 tool_call 载荷形态中提取 shell 命令。ChatPanel 实现 vscode.Disposable，公开 show()（创建或复用 webview 面板，ViewColumn.Beside，启用脚本并保留隐藏时上下文）、postToWebview(msg) 与 dispose()。消息缓冲语义在 postToWebview 中：面板不存在时直接丢弃；webview 未就绪时除 debug_log 外的消息进入 pendingWebviewMessages 队列，收到 ready 后由 flushPendingMessages 冲洗。
+
+Sources / 来源：[jiuwenswarm/channels/ide/packages/vscode-extension/src/terminal/TerminalManager.ts:L9–L28](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/vscode-extension/src/terminal/TerminalManager.ts#L9-L28), [jiuwenswarm/channels/ide/packages/vscode-extension/src/terminal/TerminalManager.ts:L34–L48](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/vscode-extension/src/terminal/TerminalManager.ts#L34-L48), [jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L63–L112](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts#L63-L112)
+
+<!-- kb:knowledge owner=ide-vscode facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**jiuwenswarm.* 工作区设置（调用点读取）**
+
+ChatPanel 通过 vscode.workspace.getConfiguration('jiuwenswarm') 在调用点读取设置，所示代码中的回退值为：rewindEnabled=true（编辑前快照）、useDiffViewer=false（默认直接应用编辑）、runCommandsInTerminal=true（bash/run_command 镜像到 IDE 终端）、loadHistoryOnSwitch=true（切换会话时按 historyLoadedForSession 守卫只加载一次历史）、defaultMode='code.plan'、gitEnabled=false（为 false 时不执行 git 状态采集与提交/推送处理分支）。注意 useDiffViewer 开启后仍有例外：无法计算拟议内容时回退为直接应用，用户拒绝 diff 时不应用编辑。所示片段未包含这些设置在 package.json 中的注册默认值；JetBrains 文档的设置表描述的是 JetBrains 插件，不能直接当作 VS Code 的注册配置。
+
+Sources / 来源：[jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L369–L404](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts#L369-L404), [jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L548–L557](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts#L548-L557), [jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L657–L674](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts#L657-L674), [jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L949–L965](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts#L949-L965)
+
+<!-- kb:knowledge owner=ide-vscode facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**调试日志开关与回退结果上报**
+
+所示片段中可观察的验证入口有二：webview 的 toggle_debug 消息切换 debugEnabled，debug() 据此把带 [JiuwenSwarm] 前缀的日志输出到控制台并转发 debug_log 到 webview，覆盖发送、快照、diff、终端等关键路径；回退操作后 handleRewind 统计恢复与失败文件数并以 rewind_done 消息（如 "Rewound N file(s), M failed"）回报给 webview。
+
+Sources / 来源：[jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L199–L203](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts#L199-L203), [jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L1003–L1008](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts#L1003-L1008), [jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts:L929–L940](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts#L929-L940)
+
diff --git a/knowledge/repos/jiuwenswarm/components/launch/_index.md b/knowledge/repos/jiuwenswarm/components/launch/_index.md
index e028a5eb..fd9911e8 100644
--- a/knowledge/repos/jiuwenswarm/components/launch/_index.md
+++ b/knowledge/repos/jiuwenswarm/components/launch/_index.md
@@ -20,7 +20,8 @@ sources: []
 
 | PR 描述在做什么 | 精确规则 | 第一批 live 源码 |
 |---|---|---|
-| start_services、jiuwenswarm-start、debug launcher、multi-instance、--dotenv、--name、… | 入口 | `jiuwenswarm/start_services.py`、`jiuwenswarm/dotenv_early.py`、`jiuwenswarm/init_workspace.py`、`jiuwenswarm/instance_manager/` |
+| start_services、jiuwenswarm-start、debug launcher、multi-instance、--dotenv、--name、… | 入口 | `jiuwenswarm/start_services.py`、`jiuwenswarm/dotenv_early.py`、`jiuwenswarm/init_workspace.py` |
+
 
 - [启动与实例隔离的设计取舍](design-tradeoffs.md) — 设计选择、收益与代价，以及 API、配置和关联功能入口。
 - [初始化与服务启动 功能知识](feature-bootstrap.md)
@@ -35,3 +36,4 @@ sources: []
 - [初始化与服务启动：实现深读](feature-depth-bootstrap.md)
 - [单机多实例：实现深读](feature-depth-instances.md)
 - [桌面宿主与自动更新：实现深读](feature-depth-desktop.md)
+- [launch 组件基础：桌面外壳 desktop_app 的启动编排](knowledge.md)
diff --git a/knowledge/repos/jiuwenswarm/components/launch/feature-bootstrap.md b/knowledge/repos/jiuwenswarm/components/launch/feature-bootstrap.md
index aaaa662e..c4b59fb5 100644
--- a/knowledge/repos/jiuwenswarm/components/launch/feature-bootstrap.md
+++ b/knowledge/repos/jiuwenswarm/components/launch/feature-bootstrap.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/安装指南.md
 feature: "bootstrap"
 entry_points: ["jiuwenswarm/init_workspace.py"]
-source_globs: ["jiuwenswarm/init_workspace.py"]
+source_globs: ["jiuwenswarm/init_workspace.py", "jiuwenswarm/server/agent_ws_server.py", "jiuwenswarm/app.py", "jiuwenswarm/common/config.py", "jiuwenswarm/common/utils.py", "jiuwenswarm/debug_launcher.py", "jiuwenswarm/resources/agent/workspace/skills/delayed-restart-app/launch_delayed_restart.py", "jiuwenswarm/server/lifecycle.py", "jiuwenswarm/gateway/app_gateway.py", "jiuwenswarm/gateway/__init__.py", "jiuwenswarm/gateway/channel_manager/channel_manager.py", "scripts/harmony_entry.py", "jiuwenswarm/common/process_supervision.py", "jiuwenswarm/runtime/service.py", "jiuwenswarm/start_services.py"]
 ---
 
 # 初始化与服务启动 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/launch/feature-desktop.md b/knowledge/repos/jiuwenswarm/components/launch/feature-desktop.md
index f9ff2a93..6f6353a5 100644
--- a/knowledge/repos/jiuwenswarm/components/launch/feature-desktop.md
+++ b/knowledge/repos/jiuwenswarm/components/launch/feature-desktop.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/windows自动更新设计.md
 feature: "desktop"
 entry_points: ["jiuwenswarm/channels/desktop/desktop_app.py"]
-source_globs: ["jiuwenswarm/channels/desktop/desktop_app.py", "jiuwenswarm/channels/desktop/*"]
+source_globs: ["jiuwenswarm/channels/desktop/desktop_app.py", "jiuwenswarm/channels/desktop/*", "jiuwenswarm/channels/web/frontend/src/utils/desktopSave.ts", "jiuwenswarm/channels/web/frontend/src/components/DesktopBrowserPane/DesktopBrowserPane.css", "jiuwenswarm/channels/web/frontend/src/components/DesktopBrowserPane/index.tsx", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/general/GeneralSettings.tsx", "scripts/build-electron-exe.ps1", "scripts/build-electron-exe.sh", "jiuwenswarm/channels/desktop/electron/main.cjs", "jiuwenswarm/channels/desktop/electron/preload.cjs", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/index.tsx", "jiuwenswarm/common/updater.py", "jiuwenswarm/channels/web/frontend/src/features/workspace/localFilePicker.ts", "jiuwenswarm/channels/web/frontend/src/hooks/useDesktopLocalFilePickerReady.ts", "scripts/build-exe.bat", "scripts/build-exe.ps1", "jiuwenswarm/channels/web/frontend/src/utils/textEditCommands.ts", "jiuwenswarm/channels/web/frontend/src/components/DesktopTextEditContextMenu/DesktopTextEditContextMenu.css", "jiuwenswarm/channels/web/frontend/src/components/DesktopTextEditContextMenu/index.tsx", "scripts/installer-electron.iss", "jiuwenswarm/channels/desktop/electron/launch.cjs", "scripts/build-macos.sh", "jiuwenswarm/common/upgrade_executor.py", "jiuwenswarm/channels/desktop/electron/target_mcp_wrapper.cjs", "scripts/jiuwenswarm.spec", "scripts/installer.iss", "jiuwenswarm/common/version_source.py", "jiuwenswarm/common/updater_restart_helper.py", "jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py", "jiuwenswarm/channels/web/app_web.py", "jiuwenswarm/channels/web/frontend/src/components/UpdatePanel/index.tsx", "jiuwenswarm/channels/web/frontend/src/App.tsx"]
 ---
 
 # 桌面宿主与自动更新 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/launch/feature-instances.md b/knowledge/repos/jiuwenswarm/components/launch/feature-instances.md
index 0a3cf1bf..ca13b560 100644
--- a/knowledge/repos/jiuwenswarm/components/launch/feature-instances.md
+++ b/knowledge/repos/jiuwenswarm/components/launch/feature-instances.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/单机多实例运行.md
 feature: "instances"
 entry_points: ["jiuwenswarm/instance_manager/bootstrap.py"]
-source_globs: ["jiuwenswarm/instance_manager/bootstrap.py", "jiuwenswarm/instance_manager/*.py"]
+source_globs: ["jiuwenswarm/instance_manager/bootstrap.py", "jiuwenswarm/instance_manager/*.py", "jiuwenswarm/dotenv_early.py", "jiuwenswarm/gateway/app_gateway.py", "jiuwenswarm/instance_manager/__init__.py", "jiuwenswarm/instance_manager/config.py", "jiuwenswarm/instance_manager/lock.py", "jiuwenswarm/start_services.py", "jiuwenswarm/instance_manager/status.py", "jiuwenswarm/instance_manager/yaml.py"]
 ---
 
 # 单机多实例 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/launch/knowledge.md b/knowledge/repos/jiuwenswarm/components/launch/knowledge.md
new file mode 100644
index 00000000..af8dcdf3
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/launch/knowledge.md
@@ -0,0 +1,43 @@
+---
+title: "launch 组件基础：桌面外壳 desktop_app 的启动编排"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/desktop/desktop_app.py:L1230-L1284, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/desktop/desktop_app.py:L1287-L1427, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/desktop-electron-packaging.md:L216-L232, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/desktop/desktop_app.py:L340-L381, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/desktop/desktop_app.py:L443-L492, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/desktop-electron-packaging.md:L29-L41, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/desktop/desktop_app.py:L1087-L1137, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/desktop/desktop_app.py:L1693-L1904, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/desktop/desktop_app.py:L710-L774, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/desktop/desktop_app.py:L1230-L1278, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/desktop/desktop_app.py:L1287-L1389]
+---
+
+# launch 组件基础：桌面外壳 desktop_app 的启动编排
+
+<!-- kb:knowledge owner=launch facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**桌面主进程作为三服务的编排者**
+
+desktop_app.py 的 DesktopRuntime.start_services 是桌面启动的控制流核心：先做 Gateway 单例预检（防止同一 workspace 双开导致 cron 重复调度），再依次拉起 web 静态服务、AgentServer 与 Gateway 三个托管子进程，并用三个并行等待线程分别探测 agent/gateway 的 TCP 就绪与 web 的 HTTP 就绪，任一失败即终止全部子进程树。web 静态页就绪即触发先行导航（on_web_ready），界面骨架先于后端就绪展示，API/WS 由前端重连逻辑补齐。启动成功后还有一个 daemon 看护线程保持 agent/gateway 成对存活：任一退出立即终止另一方，防止端口、cron 与单例锁泄漏。Electron 壳文档将这一流程标注为与 Python 桌面对齐的参照物。
+
+Sources / 来源：[jiuwenswarm/channels/desktop/desktop_app.py:L1230–L1284](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/desktop/desktop_app.py#L1230-L1284), [jiuwenswarm/channels/desktop/desktop_app.py:L1287–L1427](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/desktop/desktop_app.py#L1287-L1427), [docs/zh/desktop-electron-packaging.md:L216–L232](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/docs/zh/desktop-electron-packaging.md#L216-L232)
+
+<!-- kb:knowledge owner=launch facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**端口组与子进程环境契约**
+
+resolve_desktop_ports 复用 instance_manager 的 find_available_ports（base + index×1000，scan 默认 10 组），docstring 明确结果只存在于本次进程内存与子进程 env，不落盘；BASE_PORTS 文档给出 agentServer=18092、gatewayApi=19000、frontend=5173。_build_child_env 为所有子进程注入 JIUWENSWARM_DESKTOP=1、JIUWENSWARM_RUNTIME_WORKSPACE_READY=1 及整套会话端口（WEB_PORT/GATEWAY_PORT/AGENT_SERVER_PORT=AGENT_PORT/FRONTEND_PORT），并删除陈旧 AGENT_SERVER_URL 防止 .env 里的旧 URL 绕过重映射端口；JIUWENSWARM_START_CMD 缺省时记录本次 argv 供更新器构造重启命令。桌面 token 仅注入 web 子进程，其他子进程主动剔除。
+
+Sources / 来源：[jiuwenswarm/channels/desktop/desktop_app.py:L340–L381](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/desktop/desktop_app.py#L340-L381), [jiuwenswarm/channels/desktop/desktop_app.py:L443–L492](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/desktop/desktop_app.py#L443-L492), [docs/zh/desktop-electron-packaging.md:L29–L41](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/docs/zh/desktop-electron-packaging.md#L29-L41)
+
+<!-- kb:knowledge owner=launch facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**桌面会话锁定与 Windows 托盘/关闭策略**
+
+桌面锁：DesktopRuntime 每次启动生成 secrets.token_urlsafe(32)，首个导航 URL 以 ?dt=<token> 携带，由 web 静态服务换取 HttpOnly Cookie，浏览器直接打开对话页面则返回 403；日志展示用不含 token 的 frontend_display_url。Windows 关闭行为：_on_closing 读取 workspace 下 desktop-window.json 的 close_action（ask/hide/quit），ask 时弹出 WinForms 原生对话框询问隐藏到托盘还是退出并可记住选择；hide 走 NotifyIcon 托盘（显示并最大化/退出菜单），macOS 则通过拦截 windowShouldClose: 与 reopen 事件实现关窗不退应用。
+
+Sources / 来源：[jiuwenswarm/channels/desktop/desktop_app.py:L1087–L1137](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/desktop/desktop_app.py#L1087-L1137), [jiuwenswarm/channels/desktop/desktop_app.py:L1693–L1904](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/desktop/desktop_app.py#L1693-L1904)
+
+<!-- kb:knowledge owner=launch facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**pywebview 桥接方法与服务启动生命周期**
+
+_WindowApi 是暴露给 WebView 内 JS 的桥接对象：一部分方法（如 minimize_window/close_window、blob 保存四步事务 begin/append/finish/abort）薄委托给 DesktopRuntime 同名实现；另一些方法在桥接层直接实现行为——open_external_url 自行校验目标 URL 必须匹配 SkillHub OAuth 基址（环境变量或默认 swarmskills.openjiuwen.com）且路径限于 gitcode/github 两个 start 端点后才调用系统浏览器，download_file 会把以 / 开头的相对 URL 改写为前端 host:port 的完整地址。DesktopRuntime.start_services 是主生命周期入口：先 _preflight_gateway_singleton 拒绝同工作区二次启动（等待至多 15s），再依次拉起 web、agent、gateway 子进程，并用三个线程并行等待就绪（超时 STARTUP_TIMEOUT_SECONDS=120s）；任一等待失败立即终止全部进程树，全部结束后若 startup_errors 非空则抛出第一个错误——但在此之前先检查 _startup_cancelled，窗口关闭导致的取消优先于等待错误抛出。web 的 HTTP 就绪会触发一次 on_web_ready 回调（先行导航），不必等 agent/gateway 就绪。
+
+Sources / 来源：[jiuwenswarm/channels/desktop/desktop_app.py:L710–L774](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/desktop/desktop_app.py#L710-L774), [jiuwenswarm/channels/desktop/desktop_app.py:L1230–L1278](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/desktop/desktop_app.py#L1230-L1278), [jiuwenswarm/channels/desktop/desktop_app.py:L1287–L1389](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/desktop/desktop_app.py#L1287-L1389)
+
diff --git a/knowledge/repos/jiuwenswarm/components/login-auth/_index.md b/knowledge/repos/jiuwenswarm/components/login-auth/_index.md
index c2e679d8..719a99ac 100644
--- a/knowledge/repos/jiuwenswarm/components/login-auth/_index.md
+++ b/knowledge/repos/jiuwenswarm/components/login-auth/_index.md
@@ -18,10 +18,7 @@ sources: []
 
 | PR 描述在做什么 | 精确规则 | 第一批 live 源码 |
 |---|---|---|
-| 登录、华为账号、Account Kit、OAuth、PKCE、id_token、refresh_token、免费模型、积分、APIG、远端配置、auth | 入口 | `jiuwenswarm/common/auth/service.py`、`jiuwenswarm/common/auth/account_kit.py` |
-| 登录会话落盘、加密存档、Gateway/AgentServer 共享登录态 | 入口 | `jiuwenswarm/common/auth/session_store.py` |
-| Gateway 转发前的凭据消毒与注入、`jiuwen-login:` 句柄、请求钩子、推送续期 | 入口 | `jiuwenswarm/common/auth/passthrough.py`、`jiuwenswarm/common/auth/login_credentials.py` |
-| 登录模型列表、目录缓存、`login_model_settings` | 入口 | `jiuwenswarm/common/auth/model_catalog.py` |
+| 登录、华为账号、Account Kit、OAuth、PKCE、id_token、refresh_token、免费模型、积分、APIG、远端配置、auth | 入口 | `jiuwenswarm/common/auth/service.py`、`jiuwenswarm/common/auth/account_kit.py`、`jiuwenswarm/common/auth/session_store.py` |
 
 ## 专题入口
 
@@ -31,3 +28,4 @@ sources: []
 - [账号登录与凭据续期 功能知识](feature-login.md)
 - [login-auth 源码接口与集成边界 01](source-contracts-01.md)
 - [账号登录与凭据续期：实现深读](feature-depth-login.md)
+- [login-auth：华为账号登录与免费模型凭据（common/auth）](knowledge.md)
diff --git a/knowledge/repos/jiuwenswarm/components/login-auth/feature-login.md b/knowledge/repos/jiuwenswarm/components/login-auth/feature-login.md
index 918e43f7..ff18ab84 100644
--- a/knowledge/repos/jiuwenswarm/components/login-auth/feature-login.md
+++ b/knowledge/repos/jiuwenswarm/components/login-auth/feature-login.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/华为账号登录.md
 feature: "login"
 entry_points: ["jiuwenswarm/common/auth/service.py"]
-source_globs: ["jiuwenswarm/common/auth/service.py", "jiuwenswarm/common/auth/*.py"]
+source_globs: ["jiuwenswarm/common/auth/service.py", "jiuwenswarm/common/auth/*.py", "jiuwenswarm/extensions/agentos/agentos_router/agentos_authenticator.py", "jiuwenswarm/channels/web/frontend/src/services/authClient.ts", "jiuwenswarm/common/auth/session_store.py", "jiuwenswarm/gateway/channel_manager/web/web_http_auth.py", "jiuwenswarm/gateway/app_gateway.py", "jiuwenswarm/gateway/message_handler/message_handler.py", "jiuwenswarm/common/auth/__init__.py", "jiuwenswarm/common/auth/account_kit.py", "jiuwenswarm/channels/web/hub_oauth.py", "jiuwenswarm/channels/web/frontend/src/components/AssetPublishDrawer/index.tsx", "jiuwenswarm/channels/web/app_web.py", "jiuwenswarm/common/auth/login_credentials.py", "jiuwenswarm/common/auth/passthrough.py", "jiuwenswarm/server/runtime/agent_adapter/interface_deep.py", "jiuwenswarm/common/auth/net.py", "jiuwenswarm/common/auth/session_owners.py", "jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/models/OpenAIAccountField.tsx", "jiuwenswarm/common/auth/remote_config.py", "jiuwenswarm/channels/web/frontend/src/stores/authStore.ts", "jiuwenswarm/channels/web/frontend/src/components/LoginDialog/LoginDialog.css", "jiuwenswarm/channels/web/frontend/src/components/LoginDialog/index.tsx", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/models/OpenAIAccountField.css"]
 ---
 
 # 账号登录与凭据续期 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/login-auth/knowledge.md b/knowledge/repos/jiuwenswarm/components/login-auth/knowledge.md
new file mode 100644
index 00000000..959537fb
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/login-auth/knowledge.md
@@ -0,0 +1,53 @@
+---
+title: "login-auth：华为账号登录与免费模型凭据（common/auth）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/common/auth/remote_config.py:L45-L49, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/common/auth/remote_config.py:L161-L166, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/common/auth/account_kit.py:L135-L151, "openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/华为账号登录.md:L69-L74", openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/common/auth/service.py:L3-L11, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/common/auth/service.py:L308-L319, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/common/auth/passthrough.py:L27-L57, "openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/华为账号登录.md:L249-L253", openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/common/auth/model_catalog.py:L200-L252, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/common/auth/apig.py:L295-L315, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/common/auth/apig.py:L46-L48, "openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/华为账号登录.md:L386-L393", openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/common/auth/service.py:L322-L325, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/common/auth/remote_config.py:L300-L305, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/common/auth/service.py:L69-L79, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/common/auth/service.py:L161-L180, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/common/auth/service.py:L312-L332, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/common/auth/service.py:L335-L357]
+---
+
+# login-auth：华为账号登录与免费模型凭据（common/auth）
+
+<!-- kb:knowledge owner=login-auth facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**配置来源与开关**
+
+本地唯一的配置项是环境变量 JIUWENSWARM_CONFIG_URL（config_url()）：未设时用 DEFAULT_CONFIG_URL（https://aigw.openjiuwen.com/v1/config），显式设成空串/off/none/false/0/disabled 之一即彻底关闭（一个请求都不发）。其余配置全部由该远端接口下发：OAuthConfig.from_remote 从 huaweiaccount_login 段读 client_id（默认 118944053）、redirect_uri（默认 http://localhost:19000/api/v1/auth/callback）、scope（默认 openid profile）、exchange_url、callback_url、claim_url、account_center_url；gateway 段给 base_url 与 models/quota/invoke 路径（默认 /v1/models、/v1/usage、/v1），未给 base_url 表示能登录但没有免费模型。
+
+Sources / 来源：[jiuwenswarm/common/auth/remote_config.py:L45–L49](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/common/auth/remote_config.py#L45-L49), [jiuwenswarm/common/auth/remote_config.py:L161–L166](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/common/auth/remote_config.py#L161-L166), [jiuwenswarm/common/auth/account_kit.py:L135–L151](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/common/auth/account_kit.py#L135-L151), [docs/zh/华为账号登录.md:L69–L74](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/docs/zh/%E5%8D%8E%E4%B8%BA%E8%B4%A6%E5%8F%B7%E7%99%BB%E5%BD%95.md#L69-L74)
+
+<!-- kb:knowledge owner=login-auth facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**职责分层与凭据数据流**
+
+AuthService 是各 channel 共用的唯一登录入口，把流程（AccountKitFlow，OAuth2 授权码 + PKCE）和会话（AuthSessionStore）粘起来：发起授权 / 回调 / 认领 / 登出接在 HTTP 路由上，模型层经 live_session / resolve_id_token 取凭据；它以进程级单例 get_auth_service() 提供。凭据向 AgentServer 的传递由 passthrough.normalize_model_auth 完成：先无条件删除客户端传来的 _model_auth 键，之后仅当请求使用登录模型且能取到该会话凭据时，才由服务端挂上 {api_base, api_key=id_token, credential_ref}；AgentServer 侧模型配置里只放句柄占位值，真实 id_token 按句柄登记进凭据表。
+
+Sources / 来源：[jiuwenswarm/common/auth/service.py:L3–L11](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/common/auth/service.py#L3-L11), [jiuwenswarm/common/auth/service.py:L308–L319](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/common/auth/service.py#L308-L319), [jiuwenswarm/common/auth/passthrough.py:L27–L57](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/common/auth/passthrough.py#L27-L57), [docs/zh/华为账号登录.md:L249–L253](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/docs/zh/%E5%8D%8E%E4%B8%BA%E8%B4%A6%E5%8F%B7%E7%99%BB%E5%BD%95.md#L249-L253)
+
+<!-- kb:knowledge owner=login-auth facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**登录模型目录发现与推理错误分类**
+
+登录模型是发现出来的：get_models 用登录用户的 id_token 请求 APIG 模型列表，受远端配置门控（config 为 None 或 is_effective=false 一律返回空，本地缓存也不给），进程内 memo 命中需同时满足 30 分钟 TTL 和缓存文件 mtime 未变（Gateway 写、AgentServer 另一进程要读到），刷新失败 30 秒内不再重试并继续用旧目录。推理错误分类 classify_model_error 有优先级：先匹配 apig.xxxx 错误码（0305/0307/0316/0319 → login_required，0308 → rate_limited），再判额度耗尽（402 状态或 budget_exceeded 等文本提示 → quota_exhausted），然后才是限流；HTTP 状态码只在前缀为 error code / status 的上下文里匹配，裸数字不算。
+
+Sources / 来源：[jiuwenswarm/common/auth/model_catalog.py:L200–L252](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/common/auth/model_catalog.py#L200-L252), [jiuwenswarm/common/auth/apig.py:L295–L315](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/common/auth/apig.py#L295-L315), [jiuwenswarm/common/auth/apig.py:L46–L48](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/common/auth/apig.py#L46-L48)
+
+<!-- kb:knowledge owner=login-auth facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**测试入口与测试挂钩**
+
+文档第八节列出验证入口：tests/unit_tests/common/test_auth_*.py 覆盖 auth 模块，tests/unit_tests/gateway/test_web_http_auth_routes.py 走 authorize → callback → claim 全链路。源码为测试提供进程级替换挂钩：reset_auth_service_for_test(service) 直接设置 AuthService 单例，remote_config.set_config_for_test(config) 覆盖缓存的远端配置并复位退避状态；这些挂钩的存在不证明测试如何替身网络调用，测试体不在本次所示范围内。
+
+Sources / 来源：[docs/zh/华为账号登录.md:L386–L393](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/docs/zh/%E5%8D%8E%E4%B8%BA%E8%B4%A6%E5%8F%B7%E7%99%BB%E5%BD%95.md#L386-L393), [jiuwenswarm/common/auth/service.py:L322–L325](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/common/auth/service.py#L322-L325), [jiuwenswarm/common/auth/remote_config.py:L300–L305](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/common/auth/remote_config.py#L300-L305)
+
+<!-- kb:knowledge owner=login-auth facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**AuthService 登录入口与模型层取凭据**
+
+登录服务的公共入口是进程级单例 `AuthService`（`get_auth_service()` 双检锁构造）。`create_authorization_request()` 返回 `{authorizeUrl, state, claimToken, expiresIn}`，由调用方负责打开浏览器；回调落 ECS 鉴权服务（配置了 `callback_url`）时还会顺带起后台轮询线程去认领授权码。`claim(state, claim_token)` 供发起方取回结果：回调还没到时返回 `None`，登录失败抛 `OAuthError`；`cancel` 放弃本次登录，`logout(session_id)` 只清指定会话（无 id 时什么都不做），`status` 返回不含 token 的登录状态视图。
+
+模型层取凭据走模块级函数：`live_session(session_id, allow_refresh=True)` 严格按传入的 session id 解析会话（无 id 即视为未登录，绝不退回「本机唯一登录用户」），拿到会话再经 `ensure_fresh` 保证凭据可用，返回 `AuthSession`；解析不到会话时抛 `ModelAuthRequired("请先登录后再使用该模型", "not_logged_in")`——构造签名为 `(message, reason="not_logged_in")`，message 是异常文本，`reason` 是单独的属性，供前端区分 `not_logged_in` 与 `session_expired`。`resolve_id_token` 是其便捷形式，直接返回 `credential.id_token` 用于 `Authorization: Bearer` 头。`allow_refresh=False` 供不能阻塞的调用方：续期改在后台线程做，本次先用未过期的旧 token。
+
+Sources / 来源：[jiuwenswarm/common/auth/service.py:L69–L79](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/common/auth/service.py#L69-L79), [jiuwenswarm/common/auth/service.py:L161–L180](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/common/auth/service.py#L161-L180), [jiuwenswarm/common/auth/service.py:L312–L332](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/common/auth/service.py#L312-L332), [jiuwenswarm/common/auth/service.py:L335–L357](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/common/auth/service.py#L335-L357)
+
diff --git a/knowledge/repos/jiuwenswarm/components/observability/_index.md b/knowledge/repos/jiuwenswarm/components/observability/_index.md
index 63826427..76ec7627 100644
--- a/knowledge/repos/jiuwenswarm/components/observability/_index.md
+++ b/knowledge/repos/jiuwenswarm/components/observability/_index.md
@@ -30,3 +30,4 @@ sources: []
 - [observability 源码接口与集成边界 01](source-contracts-01.md)
 - [执行轨迹与保留：实现深读](feature-depth-observability.md)
 - [Debug Dump 与 OTel：实现深读](feature-depth-debug-trace.md)
+- [JiuwenSwarm 可观测性：轨迹存储路由、有界写入与每会话 SQLite（jiuwenswarm/observability）](knowledge.md)
diff --git a/knowledge/repos/jiuwenswarm/components/observability/feature-debug-trace.md b/knowledge/repos/jiuwenswarm/components/observability/feature-debug-trace.md
index 2daf811e..e6fb0183 100644
--- a/knowledge/repos/jiuwenswarm/components/observability/feature-debug-trace.md
+++ b/knowledge/repos/jiuwenswarm/components/observability/feature-debug-trace.md
@@ -11,7 +11,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/调试追踪.md
 feature: "debug-trace"
 entry_points: ["jiuwenswarm/server/runtime/debug_trace/config.py", "jiuwenswarm/server/runtime/debug_trace/stream_logger.py"]
-source_globs: ["jiuwenswarm/server/runtime/debug_trace/config.py", "jiuwenswarm/server/runtime/debug_trace/stream_logger.py", "jiuwenswarm/server/runtime/debug_trace/*.py"]
+source_globs: ["jiuwenswarm/server/runtime/debug_trace/config.py", "jiuwenswarm/server/runtime/debug_trace/stream_logger.py", "jiuwenswarm/server/runtime/debug_trace/*.py", "jiuwenswarm/server/runtime/agent_adapter/interface_deep.py", "jiuwenswarm/common/debug_dump.py", "jiuwenswarm/server/runtime/debug_trace/paths.py", "jiuwenswarm/server/runtime/debug_trace/context.py", "jiuwenswarm/server/runtime/debug_trace/directives.py", "jiuwenswarm/server/runtime/debug_trace/subagent_capture.py", "jiuwenswarm/server/runtime/debug_trace/task_tool_patch.py", "jiuwenswarm/channels/web/frontend/vite.config.ts", "deploy/observability/upload_traces_to_langfuse.py", "jiuwenswarm/server/runtime/agent_adapter/team_helpers.py"]
 ---
 
 # Debug Dump 与 OTel 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/observability/feature-observability.md b/knowledge/repos/jiuwenswarm/components/observability/feature-observability.md
index d25faed9..7196a74f 100644
--- a/knowledge/repos/jiuwenswarm/components/observability/feature-observability.md
+++ b/knowledge/repos/jiuwenswarm/components/observability/feature-observability.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/日志.md
 feature: "observability"
 entry_points: ["jiuwenswarm/observability/sink.py"]
-source_globs: ["jiuwenswarm/observability/sink.py", "jiuwenswarm/observability/*.py"]
+source_globs: ["jiuwenswarm/observability/sink.py", "jiuwenswarm/observability/*.py", "jiuwenswarm/agents/harness/agent_observability.py", "jiuwenswarm/observability/store.py", "jiuwenswarm/channels/ide/packages/shared-webview/chat.html", "jiuwenswarm/channels/web/frontend/src/features/trajectory/trajectory/compaction.ts", "jiuwenbox/src/jiuwenbox/server/app.py", "jiuwenbox/src/jiuwenbox/server/audit_logger.py", "jiuwenbox/src/jiuwenbox/models/common.py", "jiuwenswarm/channels/web/frontend/src/features/trajectory/primitives/markdown/cjkFriendlyStrong.ts", "jiuwenswarm/channels/web/frontend/src/features/trajectory/primitives/markdown/mathCompatibility.ts", "jiuwenswarm/channels/web/frontend/src/features/trajectory/primitives/markdown/parse.ts", "jiuwenswarm/channels/web/frontend/src/features/trajectory/primitives/markdown/plain-text.ts", "jiuwenswarm/agents/harness/observability_runtime.py", "jiuwenswarm/channels/web/frontend/src/features/trajectory/shared/otlp.ts", "jiuwenswarm/observability/otlp_payload.py", "jiuwenswarm/channels/web/frontend/src/features/trajectory/semconv/attributes.ts", "jiuwenswarm/channels/web/frontend/src/features/trajectory/primitives/pointer-grace.ts", "jiuwenswarm/common/runtime_log_filter.py", "jiuwenbox/src/jiuwenbox/server/sandbox_manager.py", "jiuwenswarm/agents/harness/team/team_manager.py", "jiuwenswarm/channels/web/frontend/src/features/trajectory/teamTrajectoryLanes.ts", "jiuwenswarm/channels/web/frontend/src/features/trajectory/trajectoryArchive.ts", "jiuwenswarm/channels/web/frontend/src/features/trajectory/TrajectoryPanel.tsx", "jiuwenswarm/channels/web/frontend/src/features/trajectory/projector/otel-trajectory-projector.ts", "jiuwenswarm/channels/web/frontend/src/features/trajectory/projector/attribute-resolver.ts", "jiuwenswarm/channels/web/frontend/src/features/trajectory/index.ts", "jiuwenswarm/channels/web/frontend/src/features/trajectory/trajectory/preview.ts", "jiuwenswarm/channels/web/frontend/src/features/trajectory/trajectoryCheckpoints.ts", "jiuwenswarm/channels/web/frontend/src/features/trajectory/primitives/markdown/CodeBlock.module.css", "jiuwenswarm/channels/web/frontend/src/features/trajectory/primitives/markdown/CodeBlock.tsx", "scripts/reset_trajectory_data.py", "jiuwenswarm/channels/web/frontend/src/features/trajectory/client/TrajectoryTable.tsx", "jiuwenswarm/channels/web/frontend/src/features/trajectory/primitives/Menu.module.css", "jiuwenswarm/channels/web/frontend/src/features/trajectory/primitives/Menu.tsx", "jiuwenswarm/channels/web/frontend/src/features/trajectory/client/TrajectoryExplorer.tsx", "jiuwenswarm/channels/web/frontend/src/features/trajectory/client/i18n.ts", "jiuwenswarm/channels/web/frontend/src/features/trajectory/client/theme.css", "jiuwenswarm/observability/gateway_hints.py", "jiuwenswarm/channels/web/frontend/src/features/trajectory/primitives/icons/index.tsx", "jiuwenswarm/channels/web/frontend/src/features/trajectory/primitives/icons/props.ts", "jiuwenswarm/channels/web/frontend/src/features/trajectory/primitives/JsonTree.module.css", "jiuwenswarm/channels/web/frontend/src/features/trajectory/primitives/JsonTree.tsx", "jiuwenswarm/channels/web/frontend/src/features/trajectory/trajectory/virtual-rows.ts", "jiuwenswarm/channels/web/frontend/src/features/trajectory/trajectory/model.ts", "jiuwenswarm/channels/web/frontend/src/features/trajectory/trajectory/record.ts", "jiuwenswarm/observability/models.py", "jiuwenswarm/observability/retention.py", "jiuwenswarm/channels/web/frontend/src/features/trajectory/trajectory/search-index.ts", "jiuwenswarm/observability/__init__.py", "jiuwenswarm/observability/config.py", "jiuwenswarm/channels/web/frontend/src/features/trajectory/trajectoryFrames.ts", "jiuwenswarm/channels/web/frontend/src/features/trajectory/trajectorySubjects.ts", "jiuwenswarm/channels/web/frontend/src/features/trajectory/theme/base.css", "jiuwenswarm/channels/web/frontend/src/features/trajectory/theme/context.tsx", "jiuwenswarm/channels/web/frontend/src/features/trajectory/theme/design-platform.css", "jiuwenswarm/channels/web/frontend/src/features/trajectory/theme/gradient-shadow-text.css", "jiuwenswarm/channels/web/frontend/src/features/trajectory/theme/scrollbar.css", "jiuwenswarm/channels/web/frontend/src/features/trajectory/theme/shiki.css", "jiuwenswarm/channels/web/frontend/src/features/trajectory/client/TrajectoryTimeline.module.css", "jiuwenswarm/channels/web/frontend/src/features/trajectory/client/TrajectoryTimeline.tsx", "jiuwenswarm/channels/web/frontend/src/features/trajectory/trajectory/timeline.ts", "jiuwenswarm/channels/web/frontend/src/features/trajectory/client/TrajectoryToolbar.module.css", "jiuwenswarm/channels/web/frontend/src/features/trajectory/client/TrajectoryToolbar.tsx", "jiuwenswarm/channels/web/frontend/src/features/trajectory/primitives/Tooltip.module.css", "jiuwenswarm/channels/web/frontend/src/features/trajectory/primitives/Tooltip.tsx", "jiuwenswarm/channels/web/frontend/src/features/trajectory/trajectoryTurnGaps.ts", "jiuwenswarm/channels/web/frontend/src/features/trajectory/featureConfig.ts", "jiuwenswarm/gateway/message_handler/message_handler.py", "jiuwenswarm/channels/web/frontend/src/features/trajectory/projector/trajectory-v2-reducer.ts", "jiuwenswarm/channels/web/frontend/src/features/trajectory/trajectoryLayout.ts", "jiuwenswarm/channels/web/frontend/src/features/trajectory/trajectoryWindow.ts", "jiuwenswarm/channels/web/frontend/src/features/trajectory/TeamTrajectoryWorkspace.tsx", "jiuwenswarm/gateway/channel_manager/web/web_connect.py", "jiuwenswarm/channels/web/frontend/src/App.tsx", "jiuwenswarm/channels/web/frontend/src/App.css", "jiuwenswarm/channels/browser/frontend/src/webview/chat.html"]
 ---
 
 # 执行轨迹与保留 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/observability/knowledge.md b/knowledge/repos/jiuwenswarm/components/observability/knowledge.md
new file mode 100644
index 00000000..bebc6db2
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/observability/knowledge.md
@@ -0,0 +1,43 @@
+---
+title: "JiuwenSwarm 可观测性：轨迹存储路由、有界写入与每会话 SQLite（jiuwenswarm/observability）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/observability/store.py:L549-L601, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/observability/store.py:L737-L788, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/observability/config.py:L27-L32, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/observability/sink.py:L640-L650, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/observability/sink.py:L905-L919, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/observability/config.py:L82-L99, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/observability/sink.py:L759-L794, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/observability/config.py:L16-L32, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/observability/config.py:L126-L154, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/observability/config.py:L64-L69, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/observability/config.py:L72-L79, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:tests/unit_tests/observability/test_trace_store.py:L289-L311, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:tests/unit_tests/observability/test_trace_store.py:L425-L449, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:tests/unit_tests/agentserver/test_trajectory_runtime_wiring.py:L214-L246, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:tests/unit_tests/agentserver/test_trajectory_runtime_wiring.py:L379-L412]
+---
+
+# JiuwenSwarm 可观测性：轨迹存储路由、有界写入与每会话 SQLite（jiuwenswarm/observability）
+
+<!-- kb:knowledge owner=observability facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**特性：first-wins 冲突记录、按 span 的流帧追加与终态丢弃**
+
+最终记录按 (trace_id, span_id) 唯一插入；同身份不同 raw_sha256 不覆盖旧行，而是写入 otlp_record_conflicts 表并在统计中计 conflicts——首个原始记录被保留。模型流帧按 span（trajectory_frame_spans 注册后以 span_ref 引用）追加存储、从不合并；默认 discard_final_span_frames=true 时，span 终态记录提交后其帧随即在同一事务中删除，晚到的帧也被丢弃（其 span 已有完整输出），置 false 则帧保留整个 turn 页面以支持逐帧回放。
+
+Sources / 来源：[jiuwenswarm/observability/store.py:L549–L601](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/observability/store.py#L549-L601), [jiuwenswarm/observability/store.py:L737–L788](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/observability/store.py#L737-L788), [jiuwenswarm/observability/config.py:L27–L32](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/observability/config.py#L27-L32)
+
+<!-- kb:knowledge owner=observability facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**数据流与会话分库**
+
+控制流为两级：TrajectorySessionSinkRouter 的 consume/consume_snapshot/consume_stream_frame 只做常数开销入队，路由线程按 session_id 懒创建每会话一个 TrajectoryRecordSink，并用 replace 把 database_path 换成该会话的独立库；sink 内部用有界双队列（记录与流帧分开）加单条 writer 线程批量提交 SQLite。会话库路径由 session_database_path 派生：取 session_id 的 SHA-256 hexdigest 前 2 个十六进制字符做一级目录、完整 digest 作文件名，路径不含任何用户可控组件；sweep_stale_databases 再按文件 mtime 超过 retention_days 清理无活跃 writer 的库。
+
+Sources / 来源：[jiuwenswarm/observability/sink.py:L640–L650](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/observability/sink.py#L640-L650), [jiuwenswarm/observability/sink.py:L905–L919](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/observability/sink.py#L905-L919), [jiuwenswarm/observability/config.py:L82–L99](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/observability/config.py#L82-L99), [jiuwenswarm/observability/sink.py:L759–L794](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/observability/sink.py#L759-L794)
+
+<!-- kb:knowledge owner=observability facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**trajectory_ui 配置块与解析规则**
+
+load_trajectory_store_settings 读取配置映射的 trajectory_ui 块（缺省取 get_config()），不改写用户配置：enabled 缺省 False（旧配置无此块即整体禁用），queue_size 4096、batch_size 64、flush_interval_ms 500、retention_days 7、detail_max_bytes 4MiB（解析最小 64KiB）、discard_final_span_frames 缺省 True。db_path 为空时落到 workspace/.trace/sessions，相对路径则相对 workspace，绝对路径原样使用。数值解析 _positive_int 只捕获 TypeError/ValueError：无法转换或低于最小值时回退默认值，不承诺捕获其他异常。
+
+Sources / 来源：[jiuwenswarm/observability/config.py:L16–L32](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/observability/config.py#L16-L32), [jiuwenswarm/observability/config.py:L126–L154](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/observability/config.py#L126-L154), [jiuwenswarm/observability/config.py:L64–L69](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/observability/config.py#L64-L69), [jiuwenswarm/observability/config.py:L72–L79](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/observability/config.py#L72-L79)
+
+<!-- kb:knowledge owner=observability facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**存储行为与运行时装配的既有测试入口**
+
+tests/unit_tests/observability/test_trace_store.py 直接驱动 TrajectoryStore.write_records：断言终态记录提交时清除其 span 的既有帧、discard_final_span_frames=False 时帧被保留（含迟到帧）、重放同字节不计数而内容不同的重放记为 1 个冲突且原始字节原样取回（L289–L311、L355–L373、L425–L449）。tests/unit_tests/agentserver/test_trajectory_runtime_wiring.py 通过 monkeypatch 断言 trajectory_ui.enabled 会让 agent 与 team 两条路径各调用一次 sync_trajectory_runtime 并携带解析后的 enabled/database_path，禁用时仍同步停用而不释放 provider（L214–L246、L379–L412）。所列测试片段仅为定位入口，本页未执行它们。
+
+Sources / 来源：[tests/unit_tests/observability/test_trace_store.py:L289–L311](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/tests/unit_tests/observability/test_trace_store.py#L289-L311), [tests/unit_tests/observability/test_trace_store.py:L425–L449](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/tests/unit_tests/observability/test_trace_store.py#L425-L449), [tests/unit_tests/agentserver/test_trajectory_runtime_wiring.py:L214–L246](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/tests/unit_tests/agentserver/test_trajectory_runtime_wiring.py#L214-L246), [tests/unit_tests/agentserver/test_trajectory_runtime_wiring.py:L379–L412](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/tests/unit_tests/agentserver/test_trajectory_runtime_wiring.py#L379-L412)
+
diff --git a/knowledge/repos/jiuwenswarm/components/packaging-deploy/_index.md b/knowledge/repos/jiuwenswarm/components/packaging-deploy/_index.md
index 50ffd8a6..7fe5855c 100644
--- a/knowledge/repos/jiuwenswarm/components/packaging-deploy/_index.md
+++ b/knowledge/repos/jiuwenswarm/components/packaging-deploy/_index.md
@@ -16,3 +16,4 @@ sources: []
 - [scripts](scripts/_index.md)
 - [scripts-nfs](scripts-nfs/_index.md)
 - [打包与部署：实现深读](feature-depth-deployment.md)
+- [packaging-deploy：冻结入口、容器与 yuanrong 部署链路](knowledge-packaging-deploy.md)
diff --git a/knowledge/repos/jiuwenswarm/components/packaging-deploy/feature-deployment.md b/knowledge/repos/jiuwenswarm/components/packaging-deploy/feature-deployment.md
index f5c91de3..497ce3ff 100644
--- a/knowledge/repos/jiuwenswarm/components/packaging-deploy/feature-deployment.md
+++ b/knowledge/repos/jiuwenswarm/components/packaging-deploy/feature-deployment.md
@@ -14,7 +14,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docker/Dockerfile.yr.rt.mgr
 feature: "deployment"
 entry_points: ["scripts/build-electron-exe.sh", "Dockerfile.claw", "docker/Dockerfile.claw", "docker/Dockerfile.claw.base", "docker/Dockerfile.yr.rt.mgr"]
-source_globs: ["scripts/build-electron-exe.sh", "scripts/*", "Dockerfile.claw", "docker/Dockerfile.claw", "docker/Dockerfile.claw.base", "docker/Dockerfile.yr.rt.mgr"]
+source_globs: ["scripts/build-electron-exe.sh", "scripts/*", "Dockerfile.claw", "docker/Dockerfile.claw", "docker/Dockerfile.claw.base", "docker/Dockerfile.yr.rt.mgr", "jiuwenswarm/channels/browser/frontend/eslint.config.js", "jiuwenswarm/channels/browser/frontend/scripts/pack.js", "jiuwenswarm/channels/browser/frontend/vite.config.ts", "jiuwenswarm/channels/browser/frontend/vite.content.config.ts", "jiuwenswarm/common/_build_config.py", "scripts/build_config.py", "scripts/verify_a2ui_bundle.py", "scripts/verify_gitcode_cli_bundle.py", "scripts/verify_playwright_mcp_bundle.py", "scripts/build-electron-exe.ps1", "scripts/build-exe.ps1", "scripts/jiuwenswarm_exe_entry.py", "deploy/yuanrong/gateway_handler.sh", "scripts/build-harmony.sh", "scripts/build-harmony-hap.sh", "scripts/nfs/setup_nfs_client.sh", "scripts/nfs/setup_nfs_server.sh", "scripts/nfs/teardown_nfs_client.sh", "scripts/nfs/teardown_nfs_server.sh", "scripts/verify_rsi_bundle.py", "scripts/build-runtimes.psm1", "scripts/build-runtimes.sh", "scripts/openjiuwen_team_mcp_exe_entry.py", "scripts/build_python_packages.py", "scripts/build_tui.py", "packages/jiuwenswarm-tui/setup.py", "packages/jiuwenswarm-tui/jiuwenswarm_tui/app.py", "deploy/yuanrong/web_handler.sh", "scripts/installer.iss", "scripts/jiuwenswarm.iss", "deploy/yuanrong/args_handler.sh", "deploy/yuanrong/check_handler.sh", "deploy/yuanrong/deploy.sh", "deploy/yuanrong/global_vars.sh", "deploy/yuanrong/jiuwenswarm_handler.sh", "deploy/yuanrong/envfile_handler.sh", "deploy/yuanrong/template_handler.sh", "deploy/yuanrong/cmd_handler.sh", "deploy/yuanrong/common.sh"]
 ---
 
 # 打包与部署 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/packaging-deploy/knowledge-packaging-deploy.md b/knowledge/repos/jiuwenswarm/components/packaging-deploy/knowledge-packaging-deploy.md
new file mode 100644
index 00000000..828cd6e6
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/packaging-deploy/knowledge-packaging-deploy.md
@@ -0,0 +1,43 @@
+---
+title: "packaging-deploy：冻结入口、容器与 yuanrong 部署链路"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:scripts/jiuwenswarm_exe_entry.py:L126-L164, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:scripts/jiuwenswarm_exe_entry.py:L628-L653, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:deploy/yuanrong/args_handler.sh:L46-L67, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:Makefile:L125-L155, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:deploy/yuanrong/web_handler.sh:L126-L152, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:deploy/yuanrong/web_handler.sh:L184-L197, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:scripts/build-runtimes.sh:L3-L7, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:scripts/jiuwenswarm_exe_entry.py:L599-L655, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:scripts/jiuwenswarm_exe_entry.py:L328-L342, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:Dockerfile.claw:L26-L84, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:deploy/yuanrong/args_handler.sh:L46-L56, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:deploy/yuanrong/web_handler.sh:L5-L18, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:deploy/yuanrong/web_handler.sh:L205-L217, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:Dockerfile.claw:L89-L100]
+---
+
+# packaging-deploy：冻结入口、容器与 yuanrong 部署链路
+
+<!-- kb:knowledge owner=packaging-deploy facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**公开入口：exe 分发 flag 与 deploy.sh 命令/模块**
+
+冻结 exe 通过一组 --desktop-* flag 暴露子进程入口（--desktop-run-agent/-gateway/-web/-app、--desktop-prepare-runtime-workspace、--desktop-install-external-cli、--desktop-install-update），另支持 `--doctor`、`init`、`acp` 子命令；`-m ruff` 被转发到内置原生 ruff 二进制，无参数时走单实例锁后启动桌面主程序。deploy.sh 的公共接口是 `up|down|restart` 命令加 `jiuwenswarm|gateway|web` 模块（默认三者全选）与 `--hosts` 选项，每个模块暴露 deploy_*/uninstall_* 钩子函数。
+
+Sources / 来源：[scripts/jiuwenswarm_exe_entry.py:L126–L164](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/scripts/jiuwenswarm_exe_entry.py#L126-L164), [scripts/jiuwenswarm_exe_entry.py:L628–L653](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/scripts/jiuwenswarm_exe_entry.py#L628-L653), [deploy/yuanrong/args_handler.sh:L46–L67](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/deploy/yuanrong/args_handler.sh#L46-L67)
+
+<!-- kb:knowledge owner=packaging-deploy facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证入口**
+
+Makefile 的测试目标包装 run_tests.sh 且传参各不相同：`test` 不带参数跑全量，`test-unit` 传 `-u`，`test-integration` 传 `-i`，`test-cov` 传 `-c`；`lint` 依次跑 ruff、pylint、mypy、codespell（后三者 `|| true` 容忍失败），`typecheck` 单独跑 mypy。web 部署的健康检查分支不同：systemd 模式轮询 `systemctl is-active` 加端口监听，失败时给出 journalctl 排查提示；nohup 模式用 `pgrep -f '[j]iuwenswarm-web'` 加端口监听，失败时指向 `/tmp/jiuwenswarm-web.log`。两个运行时打包脚本的头部注释都声明由 tests/unit_tests/test_desktop_electron_contract.py 钉住打包链路契约。
+
+Sources / 来源：[Makefile:L125–L155](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/Makefile#L125-L155), [deploy/yuanrong/web_handler.sh:L126–L152](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/deploy/yuanrong/web_handler.sh#L126-L152), [deploy/yuanrong/web_handler.sh:L184–L197](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/deploy/yuanrong/web_handler.sh#L184-L197), [scripts/build-runtimes.sh:L3–L7](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/scripts/build-runtimes.sh#L3-L7)
+
+<!-- kb:knowledge owner=packaging-deploy facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**冻结入口与容器/部署链路的分工**
+
+冻结 exe 的单一入口 `_dispatch()` 按固定顺序分发：`--doctor` 在业务 import 与单实例锁之前处理；随后依次是外部 CLI 安装/重置、`init`/`acp` 子命令、`--desktop-prepare-runtime-workspace`、各 `--desktop-run-*` 角色、`--desktop-install-update`，之后才是冻结模式下的 .py 脚本与 `-m` 转发；单实例锁只在无参数路径上检查，失败时尝试弹窗（仅 Windows/macOS，错误被吞掉）。容器侧 Dockerfile.claw 用并行 frontend/backend 阶段产出 Web bundle 与 uv 虚拟环境，最终镜像把 dist 同时复制进 site-packages 与源码树，CMD 为 `jiuwenswarm-start`。
+
+Sources / 来源：[scripts/jiuwenswarm_exe_entry.py:L599–L655](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/scripts/jiuwenswarm_exe_entry.py#L599-L655), [scripts/jiuwenswarm_exe_entry.py:L328–L342](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/scripts/jiuwenswarm_exe_entry.py#L328-L342), [Dockerfile.claw:L26–L84](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/Dockerfile.claw#L26-L84)
+
+<!-- kb:knowledge owner=packaging-deploy facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**yuanrong 部署模块与容器交付行为**
+
+yuanrong deploy.sh 支持 `up|down|restart` 命令与 `jiuwenswarm|gateway|web` 三个模块（缺省全选），web 模块经 `jiuwenswarm-web` 提供 frontend/dist 静态服务并把 /ws 代理到 gateway 的 WebChannel 端口，systemd 优先、nohup 回退，且服务已运行时跳过重复部署以免重启在途连接。容器最终镜像以 `jiuwenswarm-start` 启动、暴露 5173 端口，并通过 FRONTEND_HOST 让前端绑定容器外可访问的地址，而不改动源码/桌面安装使用的默认本机绑定。
+
+Sources / 来源：[deploy/yuanrong/args_handler.sh:L46–L56](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/deploy/yuanrong/args_handler.sh#L46-L56), [deploy/yuanrong/web_handler.sh:L5–L18](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/deploy/yuanrong/web_handler.sh#L5-L18), [deploy/yuanrong/web_handler.sh:L205–L217](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/deploy/yuanrong/web_handler.sh#L205-L217), [Dockerfile.claw:L89–L100](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/Dockerfile.claw#L89-L100)
+
diff --git a/knowledge/repos/jiuwenswarm/components/protocols/_index.md b/knowledge/repos/jiuwenswarm/components/protocols/_index.md
index e811aeed..77b9bf05 100644
--- a/knowledge/repos/jiuwenswarm/components/protocols/_index.md
+++ b/knowledge/repos/jiuwenswarm/components/protocols/_index.md
@@ -18,3 +18,4 @@ sources: []
 - [E2A 统一请求响应协议：实现深读](feature-depth-e2a.md)
 - [A2A 接入与 AgentCard：实现深读](feature-depth-a2a.md)
 - [ACP 与 stdio 桥接：实现深读](feature-depth-acp.md)
+- [jiuwenswarm/common/e2a：E2A 统一请求/响应协议组件知识](knowledge-protocols.md)
diff --git a/knowledge/repos/jiuwenswarm/components/protocols/feature-a2a.md b/knowledge/repos/jiuwenswarm/components/protocols/feature-a2a.md
index 5e833c46..c98b14a6 100644
--- a/knowledge/repos/jiuwenswarm/components/protocols/feature-a2a.md
+++ b/knowledge/repos/jiuwenswarm/components/protocols/feature-a2a.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/A2A.md
 feature: "a2a"
 entry_points: ["jiuwenswarm/gateway/channel_manager/protocol/a2a/a2a_connect.py"]
-source_globs: ["jiuwenswarm/gateway/channel_manager/protocol/a2a/a2a_connect.py", "jiuwenswarm/gateway/channel_manager/protocol/a2a/*.py"]
+source_globs: ["jiuwenswarm/gateway/channel_manager/protocol/a2a/a2a_connect.py", "jiuwenswarm/gateway/channel_manager/protocol/a2a/*.py", "jiuwenswarm/gateway/app_gateway.py"]
 ---
 
 # A2A 接入与 AgentCard 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/protocols/feature-acp.md b/knowledge/repos/jiuwenswarm/components/protocols/feature-acp.md
index 80857c6c..fd6cbe33 100644
--- a/knowledge/repos/jiuwenswarm/components/protocols/feature-acp.md
+++ b/knowledge/repos/jiuwenswarm/components/protocols/feature-acp.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/ACP插件使用.md
 feature: "acp"
 entry_points: ["jiuwenswarm/acp/stdio_client.py"]
-source_globs: ["jiuwenswarm/acp/stdio_client.py", "jiuwenswarm/acp/*.py"]
+source_globs: ["jiuwenswarm/acp/stdio_client.py", "jiuwenswarm/acp/*.py", "jiuwenswarm/agents/harness/common/tools/acp_chat/__init__.py", "jiuwenswarm/agents/harness/common/tools/acp_chat/tool.py", "jiuwenswarm/channels/acp/app_acp.py", "jiuwenswarm/gateway/channel_manager/protocol/acp/acp_connect.py", "scripts/run_gateway_acp.cmd", "scripts/run_gateway_acp.sh", "jiuwenswarm/agents/harness/common/tools/acp_output_tools.py", "jiuwenswarm/gateway/message_handler/message_handler.py", "jiuwenswarm/common/e2a/acp/session_updates.py", "jiuwenswarm/acp/cli.py", "jiuwenswarm/common/acp/stdio_client.py", "jiuwenswarm/acp/__init__.py", "jiuwenswarm/acp/subprocess_env.py", "jiuwenswarm/common/acp/subprocess_env.py", "jiuwenswarm/common/e2a/acp/acp_tool_updates.py", "jiuwenswarm/common/e2a/adapters.py", "jiuwenswarm/server/agent_ws_server.py"]
 ---
 
 # ACP 与 stdio 桥接 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/protocols/feature-e2a.md b/knowledge/repos/jiuwenswarm/components/protocols/feature-e2a.md
index 07a79a29..17be0c4b 100644
--- a/knowledge/repos/jiuwenswarm/components/protocols/feature-e2a.md
+++ b/knowledge/repos/jiuwenswarm/components/protocols/feature-e2a.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/E2A-protocol.md
 feature: "e2a"
 entry_points: ["jiuwenswarm/common/e2a/models.py"]
-source_globs: ["jiuwenswarm/common/e2a/models.py", "jiuwenswarm/common/e2a/*.py"]
+source_globs: ["jiuwenswarm/common/e2a/models.py", "jiuwenswarm/common/e2a/*.py", "jiuwenswarm/common/e2a/adapters.py", "jiuwenswarm/gateway/routing/agent_http_bridge.py", "jiuwenswarm/gateway/message_handler/message_handler.py", "jiuwenswarm/common/client/agent_client.py", "jiuwenswarm/gateway/routing/agent_client.py", "jiuwenswarm/server/gateway_push/__init__.py", "jiuwenswarm/server/gateway_push/transport.py", "jiuwenswarm/server/gateway_push/wire.py", "jiuwenswarm/server/agent_ws_server.py", "jiuwenswarm/server/runtime/agent_adapter/interface.py", "jiuwenswarm/server/utils/utils.py", "jiuwenswarm/server/runtime/agent_adapter/interface_deep.py", "jiuwenswarm/common/e2a/agent_compat.py", "jiuwenswarm/common/e2a/gateway_normalize.py", "jiuwenswarm/gateway/channel_manager/tui/tui_connect.py", "jiuwenswarm/common/e2a/constants.py", "jiuwenswarm/gateway/channel_manager/protocol/acp/acp_connect.py", "jiuwenswarm/common/e2a/wire_codec.py", "jiuwenswarm/server/front/connection.py", "jiuwenswarm/server/front/event_forwarder.py", "jiuwenswarm/server/front/router.py", "jiuwenswarm/server/front/protocol.py", "jiuwenswarm/server/runtime/gateway_adapter/__init__.py", "jiuwenswarm/server/runtime/gateway_adapter/base.py", "jiuwenswarm/gateway/app_gateway.py", "jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py", "jiuwenswarm/channels/ide/packages/vscode-extension/src/ui/ChatPanel.ts", "jiuwenswarm/channels/ide/packages/vscode-extension/src/client/SessionManager.ts", "jiuwenswarm/server/utils/stream_utils.py", "jiuwenswarm/common/protocol_ids.py", "jiuwenswarm/server/runtime/session/session_metadata.py", "jiuwenswarm/common/ws_diagnostics.py", "jiuwenswarm/common/ws_limits.py", "jiuwenswarm/server/ws_send.py"]
 ---
 
 # E2A 统一请求响应协议 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/protocols/knowledge-protocols.md b/knowledge/repos/jiuwenswarm/components/protocols/knowledge-protocols.md
new file mode 100644
index 00000000..eaec12c8
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/protocols/knowledge-protocols.md
@@ -0,0 +1,45 @@
+---
+title: "jiuwenswarm/common/e2a：E2A 统一请求/响应协议组件知识"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/A2A.md:L134-L152, "openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/ACP插件使用.md:L60-L86", openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/common/e2a/gateway_normalize.py:L197-L213, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/common/e2a/gateway_normalize.py:L138-L213, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/common/e2a/adapters.py:L42-L124, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/E2A-protocol.md:L21-L25, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/common/e2a/wire_codec.py:L1-L3, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/common/e2a/gateway_normalize.py:L38-L59, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/common/e2a/gateway_normalize.py:L116-L135, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/common/e2a/agent_compat.py:L28-L37, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/common/e2a/gateway_normalize.py:L61-L65, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/common/e2a/gateway_normalize.py:L93-L113, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/common/e2a/constants.py:L93-L116]
+---
+
+# jiuwenswarm/common/e2a：E2A 统一请求/响应协议组件知识
+
+<!-- kb:knowledge owner=protocols facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证入口**
+
+所提供的切片中没有针对 jiuwenswarm/common/e2a/ 的自动化测试文件，可查的验证入口是文档约定的手工联调命令：docs/zh/A2A.md §8 给出对 http://127.0.0.1:{A2A_SERVER_PORT:-19100}{A2A_SERVER_PATH:-/a2a} 的 curl 请求（非流式 method=SendMessage 与流式 SendStreamingMessage），前置条件为 AgentServer 与 Gateway 均启动且 A2A_SERVER_ENABLED=true——该链路会穿过 A2A→Message→E2A 的适配器。docs/zh/ACP插件使用.md 给出先启动主进程、再经 VS Code ACP Client 连接的端到端步骤。代码内另有规范化路径的运行时日志（[E2A][norm]、[E2A][fallback]、[E2A][enable_memory]）可用于联调观测；此处仅记录文档约定与日志钩子，不声称测试已运行。
+
+Sources / 来源：[docs/zh/A2A.md:L134–L152](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/docs/zh/A2A.md#L134-L152), [docs/zh/ACP插件使用.md:L60–L86](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/docs/zh/ACP%E6%8F%92%E4%BB%B6%E4%BD%BF%E7%94%A8.md#L60-L86), [jiuwenswarm/common/e2a/gateway_normalize.py:L197–L213](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/common/e2a/gateway_normalize.py#L197-L213)
+
+<!-- kb:knowledge owner=protocols facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**职责与边界**
+
+E2A 是 Gateway 与 AgentServer 之间使用的统一请求/响应载体：通道 Message 经 message_to_e2a 规范化为 E2AEnvelope，AgentResponse/AgentResponseChunk 经 gateway_normalize 转为 E2AResponse；ACP JSON-RPC 与 A2A SendMessage 经 adapters.py 的 envelope_from_acp_jsonrpc / envelope_from_a2a_send_message 转入 E2A，并用 E2AProvenance 记录来源协议、转换器与时间。协议本身不规定传输层，WebSocket 线路上的编码/解码与 legacy 兜底由 wire_codec.py 单独承担。
+
+Sources / 来源：[jiuwenswarm/common/e2a/gateway_normalize.py:L138–L213](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/common/e2a/gateway_normalize.py#L138-L213), [jiuwenswarm/common/e2a/adapters.py:L42–L124](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/common/e2a/adapters.py#L42-L124), [docs/zh/E2A-protocol.md:L21–L25](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/docs/zh/E2A-protocol.md#L21-L25), [jiuwenswarm/common/e2a/wire_codec.py:L1–L3](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/common/e2a/wire_codec.py#L1-L3)
+
+<!-- kb:knowledge owner=protocols facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**设计取舍**
+
+Inference / 设计推断（非作者历史意图）：
+
+设计推断：chat.delta 的流式身份字段（rid、proactive_* 等 17 个键）通过一份共享元组 _CHAT_DELTA_PASSTHROUGH_KEYS 在双向转换的两个循环中白名单透传，保证 delta 与 final 共享同一关联键、前端不重复渲染；代价是新增业务字段必须加入该名单，否则会在 E2A 往返中丢失。另一取舍是规范化失败时不丢请求，而是降级为携带 legacy 快照的兜底信封以保住可追溯性，代价是系统需并行维护正常 E2A 路径与 legacy 分支——e2a_to_agent_request 检测到兜底标记会抛 RuntimeError 要求调用方先分流。以上为从所示代码与文档边界得出的推断，不代表作者自述意图。
+
+Sources / 来源：[jiuwenswarm/common/e2a/gateway_normalize.py:L38–L59](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/common/e2a/gateway_normalize.py#L38-L59), [jiuwenswarm/common/e2a/gateway_normalize.py:L116–L135](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/common/e2a/gateway_normalize.py#L116-L135), [jiuwenswarm/common/e2a/agent_compat.py:L28–L37](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/common/e2a/agent_compat.py#L28-L37)
+
+<!-- kb:knowledge owner=protocols facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**模块级常量约定：内部键前缀与 legacy 快照大小上限**
+
+该层配置是模块常量而非配置文件：`E2A_INTERNAL_CONTEXT_KEY = "_jiuwenswarm"`（注释声明通道业务勿占用此前缀），`MAX_LEGACY_AGENT_REQUEST_JSON_BYTES = 512_000` 限制兜底 legacy 快照的 JSON 字节数——超限时仅把 `params` 替换为 `{"_e2a_fallback_error": "legacy payload too large"}`，替换后不再复查总大小。`constants.py` 定义 `E2A_WIRE_INTERNAL_METADATA_KEYS`（含 `_jiuwenswarm_server_push`、`_e2a_wire_legacy_*` 等），注释约定这些键仅用于编解码/队列语义，不得随业务 channel metadata 下发给 `Message.metadata`。
+
+Sources / 来源：[jiuwenswarm/common/e2a/gateway_normalize.py:L61–L65](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/common/e2a/gateway_normalize.py#L61-L65), [jiuwenswarm/common/e2a/gateway_normalize.py:L93–L113](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/common/e2a/gateway_normalize.py#L93-L113), [jiuwenswarm/common/e2a/constants.py:L93–L116](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/common/e2a/constants.py#L93-L116)
+
diff --git a/knowledge/repos/jiuwenswarm/components/sandbox-runtime/_index.md b/knowledge/repos/jiuwenswarm/components/sandbox-runtime/_index.md
index b4d176ba..9be8e1dc 100644
--- a/knowledge/repos/jiuwenswarm/components/sandbox-runtime/_index.md
+++ b/knowledge/repos/jiuwenswarm/components/sandbox-runtime/_index.md
@@ -23,3 +23,5 @@ sources: []
 | PR 描述在做什么 | 精确规则 | 第一批 live 源码 |
 |---|---|---|
 | sandbox runtime | 入口 | `jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy.py`、`jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy_manager.py`、`jiuwenbox/src/jiuwenbox/server/app.py` |
+
+- [sandbox-runtime（JiuwenBox 服务与推理隐私代理）](knowledge.md)
diff --git a/knowledge/repos/jiuwenswarm/components/sandbox-runtime/feature-sandbox-privacy-proxy.md b/knowledge/repos/jiuwenswarm/components/sandbox-runtime/feature-sandbox-privacy-proxy.md
index 13176965..63f9a029 100644
--- a/knowledge/repos/jiuwenswarm/components/sandbox-runtime/feature-sandbox-privacy-proxy.md
+++ b/knowledge/repos/jiuwenswarm/components/sandbox-runtime/feature-sandbox-privacy-proxy.md
@@ -11,7 +11,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/README_CN.md
 feature: "sandbox-privacy-proxy"
 entry_points: ["jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy.py", "jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy_manager.py"]
-source_globs: ["jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy.py", "jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy_manager.py"]
+source_globs: ["jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy.py", "jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy_manager.py", "jiuwenbox/src/jiuwenbox/proxy/__init__.py", "jiuwenbox/src/jiuwenbox/server/app.py", "jiuwenbox/src/jiuwenbox/server/policy_reader.py", "jiuwenbox/src/jiuwenbox/server/proxy_manager.py", "jiuwenbox/src/jiuwenbox/server/routes/proxy.py"]
 ---
 
 # JiuwenBox 推理隐私代理的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/sandbox-runtime/feature-sandbox.md b/knowledge/repos/jiuwenswarm/components/sandbox-runtime/feature-sandbox.md
index b6585c40..26f81e69 100644
--- a/knowledge/repos/jiuwenswarm/components/sandbox-runtime/feature-sandbox.md
+++ b/knowledge/repos/jiuwenswarm/components/sandbox-runtime/feature-sandbox.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/README_CN.md
 feature: "sandbox"
 entry_points: ["jiuwenbox/src/jiuwenbox/server/app.py"]
-source_globs: ["jiuwenbox/src/jiuwenbox/server/app.py", "jiuwenbox/src/jiuwenbox/*"]
+source_globs: ["jiuwenbox/src/jiuwenbox/server/app.py", "jiuwenbox/src/jiuwenbox/*", "jiuwenbox/src/jiuwenbox/supervisor/bwrap.py", "jiuwenbox/src/jiuwenbox/supervisor/cgroup.py", "jiuwenbox/src/jiuwenbox/server/runtime/process.py", "jiuwenbox/src/jiuwenbox/server/sandbox_manager.py", "jiuwenbox/src/jiuwenbox/supervisor/sandbox_daemon.py", "jiuwenbox/src/jiuwenbox/server/auth.py", "jiuwenbox/src/jiuwenbox/bundled_configs.py", "jiuwenbox/src/jiuwenbox/cli/jiuwenbox.py", "jiuwenbox/docker/Dockerfile", "jiuwenbox/scripts/build_docker.sh", "jiuwenbox/scripts/run_docker.sh", "jiuwenbox/src/jiuwenbox/models/policy.py", "jiuwenbox/src/jiuwenbox/server/routes/policy.py", "jiuwenbox/src/jiuwenbox/logging_config.py", "jiuwenbox/src/jiuwenbox/server/routes/mcp.py", "jiuwenbox/src/jiuwenbox/models/__init__.py", "jiuwenswarm/server/sandbox/jiuwenbox_runner.py", "jiuwenbox/src/jiuwenbox/server/launcher.py", "jiuwenbox/src/jiuwenbox/server/workspace.py", "jiuwenbox/src/jiuwenbox/supervisor/landlock_launcher.py", "jiuwenbox/src/jiuwenbox/supervisor/landlock.py", "jiuwenbox/src/jiuwenbox/supervisor/network.py", "jiuwenswarm/server/runtime/no_host_fallback_jiuwenbox.py", "jiuwenbox/src/jiuwenbox/server/policy_reader.py", "jiuwenswarm/common/config.py", "jiuwenswarm/agents/harness/common/tools/command_tools.py", "jiuwenswarm/server/agent_ws_server.py", "jiuwenbox/src/jiuwenbox/supervisor/daemon_ipc.py", "jiuwenswarm/server/runtime/agent_adapter/sysop_builder.py", "jiuwenswarm/server/sandbox/host_port.py", "jiuwenbox/src/jiuwenbox/models/sandbox.py", "jiuwenswarm/server/runtime/sandbox_no_host_fallback.py", "jiuwenbox/src/jiuwenbox/server/policy_engine.py", "jiuwenbox/src/jiuwenbox/server/routes/sandbox.py", "jiuwenbox/src/jiuwenbox/supervisor/seccomp.py"]
 ---
 
 # JiuwenBox 隔离执行 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/sandbox-runtime/knowledge.md b/knowledge/repos/jiuwenswarm/components/sandbox-runtime/knowledge.md
new file mode 100644
index 00000000..6b037251
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/sandbox-runtime/knowledge.md
@@ -0,0 +1,53 @@
+---
+title: "sandbox-runtime（JiuwenBox 服务与推理隐私代理）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/src/jiuwenbox/server/app.py:L260-L330, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/src/jiuwenbox/server/app.py:L332-L402, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/src/jiuwenbox/server/app.py:L207-L224, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/src/jiuwenbox/server/app.py:L83-L114, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/src/jiuwenbox/server/app.py:L227-L257, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy_manager.py:L581-L633, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy.py:L119-L123, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy.py:L189-L196, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy_manager.py:L501-L510, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy.py:L294-L306, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy.py:L167-L196, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/src/jiuwenbox/server/app.py:L275-L295, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy.py:L130-L133, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy_manager.py:L204-L210, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy_manager.py:L164-L183, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy_manager.py:L557-L579]
+---
+
+# sandbox-runtime（JiuwenBox 服务与推理隐私代理）
+
+<!-- kb:knowledge owner=sandbox-runtime facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**FastAPI lifespan 编排沙箱与代理两个子系统**
+
+box-server 的 lifespan 在启动时先抬高 RLIMIT_NOFILE 并为 asyncio 默认执行器配置线程池，再按 PolicyReader.is_proxy_only() 分流：proxy-only 模式跳过沙箱侧全部组件（无 ProcessRuntime、subreaper、僵尸/idle reaper），否则先 enable_child_subreaper、构建全局 SandboxManager 并注册 SIGCHLD 僵尸回收与 idle reaper，随后创建并启动 ProxyManager、给 UDS socket 打权限位、启动 MCP session manager。关停按固定顺序：MCP session → proxy → idle reaper → shutdown_all_sandboxes → clear_persistent_state（清空 state_dir/policies_dir）→ 注销僵尸回收器，各步均为 best-effort 只记日志。模块级单例 _sandbox_manager/_proxy_manager/_proxy_only_mode 由 lifespan 维护，get_sandbox_manager 在 proxy-only 模式下懒加载时直接抛 503。
+
+Sources / 来源：[jiuwenbox/src/jiuwenbox/server/app.py:L260–L330](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/src/jiuwenbox/server/app.py#L260-L330), [jiuwenbox/src/jiuwenbox/server/app.py:L332–L402](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/src/jiuwenbox/server/app.py#L332-L402), [jiuwenbox/src/jiuwenbox/server/app.py:L207–L224](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/src/jiuwenbox/server/app.py#L207-L224)
+
+<!-- kb:knowledge owner=sandbox-runtime facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**IO 线程数与 UDS 权限的环境变量**
+
+JIUWENBOX_IO_THREADS 控制 asyncio 默认 ThreadPoolExecutor 线程数：非整数或 <1 的值被忽略并回退到默认 max(64, cpu_count*16)。JIUWENBOX_UDS_PATH（由 launcher 写入）存在时，启动阶段按 JIUWENBOX_UDS_MODE（八进制，默认 "0666"）对 socket 文件做一次 chmod；mode 非法或 chmod 失败仅告警不阻塞启动。策略侧 load_from_policy 要求 listen_port > 0 才加载全局代理，listen_host 缺省回退 127.0.0.1。
+
+Sources / 来源：[jiuwenbox/src/jiuwenbox/server/app.py:L83–L114](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/src/jiuwenbox/server/app.py#L83-L114), [jiuwenbox/src/jiuwenbox/server/app.py:L227–L257](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/src/jiuwenbox/server/app.py#L227-L257), [jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy_manager.py:L581–L633](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy_manager.py#L581-L633)
+
+<!-- kb:knowledge owner=sandbox-runtime facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**update 重启不恢复路由启用；首读 64KiB 的头部限制**
+
+Inference / 设计推断（非作者历史意图）：
+
+update_proxy 更新某路由时若代理在运行，会先 stop 再重建 InferencePrivacyProxy；新代理的 _enabled_routes 初始为空集合，且 _match_route 只匹配已启用的前缀，重启代码也未重新调用 enable_route——因此更新后即使重启成功，所有路由（含未更新的）都不再转发请求，需要逐条重新启用。另一取舍：_handle_connection 只在首次 read(65536) 的缓冲里找 \r\n\r\n 头部结束符，找不到即回 400；但超出的请求体由 forward_remaining_request 循环读取转发，不受 64KiB 限制（推断：分片到达导致头部不完整的请求会被误判为 400）。
+
+Sources / 来源：[jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy.py:L119–L123](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy.py#L119-L123), [jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy.py:L189–L196](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy.py#L189-L196), [jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy_manager.py:L501–L510](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy_manager.py#L501-L510), [jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy.py:L294–L306](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy.py#L294-L306)
+
+<!-- kb:knowledge owner=sandbox-runtime facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**最长前缀路由与 proxy-only 部署模式**
+
+路由匹配按字符串前缀进行：'/api' 仍会字符串匹配 '/api-v2/chat'，_match_route 在所有已启用且前缀命中的路由中选前缀最长者——只有当更长、更具体的路由（如 '/api-v2'）存在且已启用时才胜出；若它未启用，请求会落到较短的 '/api' 路由上。服务器侧 lifespan 还支持 proxy-only 模式：policy 只配置 inference_privacy_proxies 时跳过构建 SandboxManager（不起 ProcessRuntime、subreaper 等），get_sandbox_manager 对沙箱 API 返回干净的 503，代理子系统照常启动。
+
+Sources / 来源：[jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy.py:L167–L196](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy.py#L167-L196), [jiuwenbox/src/jiuwenbox/server/app.py:L275–L295](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/src/jiuwenbox/server/app.py#L275-L295), [jiuwenbox/src/jiuwenbox/server/app.py:L207–L224](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/src/jiuwenbox/server/app.py#L207-L224)
+
+<!-- kb:knowledge owner=sandbox-runtime facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**面向测试的可观测性接口**
+
+代码内建有测试/管理观测接口：InferencePrivacyProxy 通过 server 属性暴露 asyncio 监听器，注释明确 "for tests and management code"；manager 提供 reset()（"Intended for isolated tests"，清空 _proxies，不加锁）与 get_global_instance()（返回 "default" 实例供测试检查）。每个 ProxyInstance 维护带 UTC 时间戳的内存日志环形缓冲，上限 1000 行，get_proxy_logs(name, lines) 返回尾部若干行。所示片段中未包含对上述行为的自动化测试本体。
+
+Sources / 来源：[jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy.py:L130–L133](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy.py#L130-L133), [jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy_manager.py:L204–L210](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy_manager.py#L204-L210), [jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy_manager.py:L164–L183](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy_manager.py#L164-L183), [jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy_manager.py:L557–L579](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/src/jiuwenbox/proxy/inference_privacy_proxy_manager.py#L557-L579)
+
diff --git a/knowledge/repos/jiuwenswarm/components/sdk-clients/_index.md b/knowledge/repos/jiuwenswarm/components/sdk-clients/_index.md
index 853150a9..b1c3b458 100644
--- a/knowledge/repos/jiuwenswarm/components/sdk-clients/_index.md
+++ b/knowledge/repos/jiuwenswarm/components/sdk-clients/_index.md
@@ -21,3 +21,5 @@ sources: []
 | PR 描述在做什么 | 精确规则 | 第一批 live 源码 |
 |---|---|---|
 | sdk clients | 入口 | `sdks/python/src/jiuwenswarm_sdk/client.py` |
+
+- [jiuwenswarm Python SDK Client (sdks/python/src/jiuwenswarm_sdk/client.py)](knowledge.md)
diff --git a/knowledge/repos/jiuwenswarm/components/sdk-clients/feature-sdk.md b/knowledge/repos/jiuwenswarm/components/sdk-clients/feature-sdk.md
index 18f566e7..74dc5524 100644
--- a/knowledge/repos/jiuwenswarm/components/sdk-clients/feature-sdk.md
+++ b/knowledge/repos/jiuwenswarm/components/sdk-clients/feature-sdk.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:sdks/README.md
 feature: "sdk"
 entry_points: ["sdks/python/src/jiuwenswarm_sdk/client.py"]
-source_globs: ["sdks/python/src/jiuwenswarm_sdk/client.py", "sdks/*"]
+source_globs: ["sdks/python/src/jiuwenswarm_sdk/client.py", "sdks/*", "jiuwenswarm/channels/process_cli/protocol/version.py", "sdks/python/src/jiuwenswarm_sdk/protocol.py", "sdks/python/src/jiuwenswarm_sdk/types.py", "sdks/typescript/src/index.ts", "sdks/typescript/src/protocol.ts", "jiuwenswarm/runtime/service.py", "sdks/python/src/jiuwenswarm_sdk/__init__.py"]
 ---
 
 # Python 与 TypeScript SDK 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/sdk-clients/knowledge.md b/knowledge/repos/jiuwenswarm/components/sdk-clients/knowledge.md
new file mode 100644
index 00000000..60dc55c5
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/sdk-clients/knowledge.md
@@ -0,0 +1,61 @@
+---
+title: "jiuwenswarm Python SDK Client (sdks/python/src/jiuwenswarm_sdk/client.py)"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:sdks/python/src/jiuwenswarm_sdk/client.py:L1-L36, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:sdks/python/src/jiuwenswarm_sdk/client.py:L101-L177, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:sdks/python/src/jiuwenswarm_sdk/client.py:L227-L233, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:sdks/python/src/jiuwenswarm_sdk/client.py:L38-L61, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:sdks/python/src/jiuwenswarm_sdk/client.py:L111-L141, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:sdks/python/src/jiuwenswarm_sdk/client.py:L240-L249, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:sdks/python/src/jiuwenswarm_sdk/client.py:L299-L356, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:sdks/README.md:L52-L59, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:sdks/README.md:L137-L148, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:sdks/python/src/jiuwenswarm_sdk/client.py:L63-L99, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:sdks/python/src/jiuwenswarm_sdk/client.py:L111-L122, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:sdks/python/src/jiuwenswarm_sdk/client.py:L140-L141, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:sdks/python/src/jiuwenswarm_sdk/client.py:L254-L261, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:sdks/python/src/jiuwenswarm_sdk/client.py:L154-L158, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:sdks/python/src/jiuwenswarm_sdk/client.py:L208-L220, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:sdks/python/src/jiuwenswarm_sdk/client.py:L238-L280, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:sdks/README.md:L79-L83]
+---
+
+# jiuwenswarm Python SDK Client (sdks/python/src/jiuwenswarm_sdk/client.py)
+
+<!-- kb:knowledge owner=sdk-clients facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**职责与数据/控制流**
+
+Client 是无 Runtime 依赖的异步薄进程宿主：每次 run/query 拉起一个子进程（默认 `jiuwenswarm-process`），encode 后的请求经 stdin 写入，stdout 逐行读取并由 protocol 的 Records.accept 校验收敛，stderr 由独立任务 drain 并只保留尾部 64 KiB。控制流在 _execute 中：写入载荷 →（query 时关闭 stdin）→ consume 处理事件与交互 → 等待进程退出与 stderr 收尾，Records.finish(exit_code) 把终端记录与 OS 退出状态对账。
+
+Sources / 来源：[sdks/python/src/jiuwenswarm_sdk/client.py:L1–L36](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/sdks/python/src/jiuwenswarm_sdk/client.py#L1-L36), [sdks/python/src/jiuwenswarm_sdk/client.py:L101–L177](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/sdks/python/src/jiuwenswarm_sdk/client.py#L101-L177), [sdks/python/src/jiuwenswarm_sdk/client.py:L227–L233](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/sdks/python/src/jiuwenswarm_sdk/client.py#L227-L233)
+
+<!-- kb:knowledge owner=sdk-clients facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**构造参数与默认值**
+
+构造参数：`command`（默认 `("jiuwenswarm-process",)`，必须是非空 argv 字符串序列，拒绝 shell 字符串）、`cwd`、`env`（非 None 时与 os.environ 合并覆盖）、`shutdown_grace_seconds=30`（须正有限）、`max_record_bytes=8*1024*1024`（须正整数）。max_record_bytes 同时作为 create_subprocess_exec 的 StreamReader limit，超限输出记录触发 ProtocolError。调用级 `deadline_seconds` 须正有限，用 asyncio.timeout 包住 I/O 与退出等待。
+
+Sources / 来源：[sdks/python/src/jiuwenswarm_sdk/client.py:L38–L61](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/sdks/python/src/jiuwenswarm_sdk/client.py#L38-L61), [sdks/python/src/jiuwenswarm_sdk/client.py:L111–L141](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/sdks/python/src/jiuwenswarm_sdk/client.py#L111-L141), [sdks/python/src/jiuwenswarm_sdk/client.py:L240–L249](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/sdks/python/src/jiuwenswarm_sdk/client.py#L240-L249)
+
+<!-- kb:knowledge owner=sdk-clients facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**清理策略与交互取舍**
+
+Inference / 设计推断（非作者历史意图）：
+
+清理是两级的：run 路径先发协议 cancel，query 路径发 SIGTERM（Windows 用 CTRL_BREAK_EVENT），在 shutdown_grace_seconds 内未退出才强制回收——POSIX 用 killpg SIGKILL 杀整个进程组、Windows 用 taskkill /T /F，均只针对本次调用拥有的子树；代码注释明确强制终止是失败兜底而非正常路径。交互设计上 SDK 不猜测权限/Plan 决策，保留 Runtime 的 answers 结构，无宿主回调即抛 InteractionRequired 而非自动批准（文档明确 ASK 是宿主决定、DENY 不放宽）。这些是接口与文档声明的选择；作者历史意图无进一步文档证据，属推断。
+
+Sources / 来源：[sdks/python/src/jiuwenswarm_sdk/client.py:L299–L356](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/sdks/python/src/jiuwenswarm_sdk/client.py#L299-L356), [sdks/README.md:L52–L59](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/sdks/README.md#L52-L59)
+
+<!-- kb:knowledge owner=sdk-clients facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**测试入口与覆盖**
+
+文档给出的入口是 `python -m pytest -o addopts='' sdks/python/tests tests/unit_tests/process_cli/test_query.py`（另有 sdks/typescript 的 npm test）。共享的真实子进程 fixture 覆盖 UTF-8 分帧、大 stderr、framing、交互、取消、回调、deadline 与进程退出，但不是真实模型的 E2E——文档要求另行在隔离环境中验证 SDK → CLI → 共享 Runtime 链路。
+
+Sources / 来源：[sdks/README.md:L137–L148](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/sdks/README.md#L137-L148)
+
+<!-- kb:knowledge owner=sdk-clients facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**Client 的公开入口与错误契约**
+
+`Client.run(request, *, on_event, on_interaction, cancel, deadline_seconds)` 接收一个 Mapping 并以 query=False 走 `_execute`；`Client.query(operation, params, *, workspace, timeout_seconds, deadline_seconds)` 组装 operation/params（可选 workspace、timeout_seconds）后以 query=True 执行，返回 `query_result` 而非活 Session。`_execute` 对非正或非有限的 `deadline_seconds` 抛 ValueError，补默认 `schema_version`/`type`/`request_id` 后 encode 写入子进程 stdin；query 用 `--query-json -` 参数、run 用 `--run-jsonl`，启动时的 OSError 包装为 `TransportError`，无自动重试。交互回调返回的 answers 会在未取消时回写 stdin（构造 `type: "answer"` 信封），但存在两个例外：回调期间已触发取消则跳过回写，stdin 已关闭时 write 直接返回。
+
+Sources / 来源：[sdks/python/src/jiuwenswarm_sdk/client.py:L63–L99](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/sdks/python/src/jiuwenswarm_sdk/client.py#L63-L99), [sdks/python/src/jiuwenswarm_sdk/client.py:L111–L122](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/sdks/python/src/jiuwenswarm_sdk/client.py#L111-L122), [sdks/python/src/jiuwenswarm_sdk/client.py:L140–L141](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/sdks/python/src/jiuwenswarm_sdk/client.py#L140-L141), [sdks/python/src/jiuwenswarm_sdk/client.py:L254–L261](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/sdks/python/src/jiuwenswarm_sdk/client.py#L254-L261)
+
+<!-- kb:knowledge owner=sdk-clients facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**stdin/stdout 承载的三类记录与失败保护**
+
+子进程 stdin 承载三种写出：初始 run/query 载荷（query 写入后即关闭 stdin）、取消时的 `type: "cancel"` 记录（由 `cancel` asyncio.Event 触发或清理阶段发送）、以及交互回调产生的 `type: "answer"` 信封；文档确认答复与取消都不会另起命令。stdout 逐行读取经 `Records.accept` 校验：超限记录抛 `ProtocolError`，流结束仍无终端结果也抛 `ProtocolError`；收到 `interaction.requested` 事件且未取消时若无 `on_interaction` 回调则抛 `InteractionRequired`（不自动批准），stderr 由独立任务 drain 并只保留尾部 64 KiB。
+
+Sources / 来源：[sdks/python/src/jiuwenswarm_sdk/client.py:L154–L158](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/sdks/python/src/jiuwenswarm_sdk/client.py#L154-L158), [sdks/python/src/jiuwenswarm_sdk/client.py:L208–L220](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/sdks/python/src/jiuwenswarm_sdk/client.py#L208-L220), [sdks/python/src/jiuwenswarm_sdk/client.py:L238–L280](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/sdks/python/src/jiuwenswarm_sdk/client.py#L238-L280), [sdks/README.md:L79–L83](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/sdks/README.md#L79-L83)
+
diff --git a/knowledge/repos/jiuwenswarm/components/subpackages/_index.md b/knowledge/repos/jiuwenswarm/components/subpackages/_index.md
index b44a0bd8..6804f7f3 100644
--- a/knowledge/repos/jiuwenswarm/components/subpackages/_index.md
+++ b/knowledge/repos/jiuwenswarm/components/subpackages/_index.md
@@ -15,3 +15,4 @@ sources: []
 - [packages-jiuwenswarm-tui](packages-jiuwenswarm-tui/_index.md)
 - [sdks-python](sdks-python/_index.md)
 - [sdks-typescript](sdks-typescript/_index.md)
+- [jiuwenbox ProcessRuntime（进程态沙箱运行时适配器）](knowledge-subpackages.md)
diff --git a/knowledge/repos/jiuwenswarm/components/subpackages/knowledge-subpackages.md b/knowledge/repos/jiuwenswarm/components/subpackages/knowledge-subpackages.md
new file mode 100644
index 00000000..1d44ed22
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/subpackages/knowledge-subpackages.md
@@ -0,0 +1,53 @@
+---
+title: "jiuwenbox ProcessRuntime（进程态沙箱运行时适配器）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/src/jiuwenbox/server/runtime/process.py:L1336-L1355, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/src/jiuwenbox/server/runtime/process.py:L2031-L2040, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/README_CN.md:L163-L166, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/src/jiuwenbox/server/runtime/process.py:L124-L127, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/src/jiuwenbox/server/runtime/process.py:L1720-L1724, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/src/jiuwenbox/server/runtime/process.py:L2-L8, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/src/jiuwenbox/server/runtime/process.py:L265-L276, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/src/jiuwenbox/server/runtime/process.py:L297-L311, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/src/jiuwenbox/server/runtime/process.py:L191-L217, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/src/jiuwenbox/server/runtime/process.py:L179-L188, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/src/jiuwenbox/server/runtime/process.py:L117-L146, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/src/jiuwenbox/server/runtime/process.py:L1204-L1214, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/src/jiuwenbox/server/runtime/process.py:L1301-L1316, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/src/jiuwenbox/server/runtime/process.py:L1055-L1072, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenbox/README_CN.md:L48-L52]
+---
+
+# jiuwenbox ProcessRuntime（进程态沙箱运行时适配器）
+
+<!-- kb:knowledge owner=subpackages facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**设计取舍**
+
+两个可考证的取舍：(1) 宿主防火墙自保护在 iptables 因无 root 返回 EPERM 时只告警并继续创建沙箱，而不是失败——注释明确说这是接受了无特权部署没有宿主级保护的后果，换取完全本地策略仍可用。(2) 僵尸回收双通道：uvloop 拒绝 SIGCHLD handler，所以周期 Task（默认 2s）作为通用兜底，代价是空闲时少量轮询 CPU，收益是峰值 <defunct> 数量极小。cgroup 迁移放在 preexec_fn（fork 后 execve 前）是因为 cgroup v2 只在 fork 时继承，事后写 cgroup.procs 会漏掉 bwrap 早先 fork 的后代。
+
+Sources / 来源：[jiuwenbox/src/jiuwenbox/server/runtime/process.py:L1336–L1355](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/src/jiuwenbox/server/runtime/process.py#L1336-L1355), [jiuwenbox/src/jiuwenbox/server/runtime/process.py:L2031–L2040](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/src/jiuwenbox/server/runtime/process.py#L2031-L2040)
+
+<!-- kb:knowledge owner=subpackages facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**测试入口**
+
+Inference / 设计推断（非作者历史意图）：
+
+README_CN 记录了集成测试双通路入口：pytest tests/integration 可分别用 --server-endpoint=http://127.0.0.1:8321（TCP）和 --server-endpoint=unix:///...（UDS）运行，对应传输层两种监听形态。process.py 自身注释提到测试会直接实例化 ProcessRuntime（如 _derive_protect_ports_from_listen 的 docstring 提到 test harness 不设 JIUWENBOX_LISTEN 的路径）以及测试中重建事件循环时 register_zombie_reaper 会替换旧注册，但本次展示的输入未包含这些测试文件本身。
+
+Sources / 来源：[jiuwenbox/README_CN.md:L163–L166](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/README_CN.md#L163-L166), [jiuwenbox/src/jiuwenbox/server/runtime/process.py:L124–L127](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/src/jiuwenbox/server/runtime/process.py#L124-L127), [jiuwenbox/src/jiuwenbox/server/runtime/process.py:L1720–L1724](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/src/jiuwenbox/server/runtime/process.py#L1720-L1724)
+
+<!-- kb:knowledge owner=subpackages facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**职责与数据流：单次 bwrap + 常驻 daemon IPC**
+
+ProcessRuntime 是进程态运行时适配器：每个沙箱生命周期只 spawn 一次 bubblewrap 来启动沙箱内常驻 daemon，之后的 exec/exec_background 请求都经 daemon IPC 服务，使命令继承同一 namespace/mount/seccomp/Landlock 包络，避免每次调用重新拉起 bwrap。控制通道是 box-server 在宿主侧 0700 目录里 bind 的 Unix listener，其 fd 通过 Popen(pass_fds=...) 一路继承给 daemon（经 LISTENER_FD_ENV 认领），沙箱内用户代码无法经文件系统触达该 socket。IPC 并非唯一通路：遇到 FATAL_DAEMON_ERRNOS 这类致命错误时会翻转 _daemon_socket_ready，后续调用退回慢速的 bash/python3 传统路径。
+
+Sources / 来源：[jiuwenbox/src/jiuwenbox/server/runtime/process.py:L2–L8](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/src/jiuwenbox/server/runtime/process.py#L2-L8), [jiuwenbox/src/jiuwenbox/server/runtime/process.py:L265–L276](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/src/jiuwenbox/server/runtime/process.py#L265-L276), [jiuwenbox/src/jiuwenbox/server/runtime/process.py:L297–L311](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/src/jiuwenbox/server/runtime/process.py#L297-L311)
+
+<!-- kb:knowledge owner=subpackages facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**环境变量：fastpath 与宿主端口保护**
+
+JIUWENBOX_PYTHON_FASTPATH 控制透明优化的开关：unset 或 "1" 开启，"0" 显式关闭，其它任何值告警并按关闭处理（fail-safe）。配套的 JIUWENBOX_PYTHON_FASTPATH_MAX_SANDBOXES 限制单进程内可激活 worker 池的沙箱数，默认 50，解析时上限钳到 1000。JIUWENBOX_SERVER_PROTECT_PORTS 未设置时从 JIUWENBOX_LISTEN 推导（http://host:port 取端口，unix:// 返回空即不保护，缺失或畸形回退默认 8321）；显式设为空字符串可整体关闭，设为逗号分隔整数列表则覆盖。
+
+Sources / 来源：[jiuwenbox/src/jiuwenbox/server/runtime/process.py:L191–L217](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/src/jiuwenbox/server/runtime/process.py#L191-L217), [jiuwenbox/src/jiuwenbox/server/runtime/process.py:L179–L188](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/src/jiuwenbox/server/runtime/process.py#L179-L188), [jiuwenbox/src/jiuwenbox/server/runtime/process.py:L117–L146](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/src/jiuwenbox/server/runtime/process.py#L117-L146), [jiuwenbox/src/jiuwenbox/server/runtime/process.py:L1204–L1214](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/src/jiuwenbox/server/runtime/process.py#L1204-L1214)
+
+<!-- kb:knowledge owner=subpackages facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**隔离特性：条件化的宿主防火墙与 Landlock daemon**
+
+network.mode: host 下会按沙箱 uid 安装 iptables OUTPUT REJECT 保护 box-server 自身端口，但该保护是条件化的：policy 未声明任何 egress/ingress 规则时跳过，环境变量设空可禁用，iptables 无 root 返回 EPERM 时只回滚部分规则、告警并继续创建沙箱。Landlock 路径上，launcher（python3 -S）先应用 Landlock，再通过 compile/exec 在同一 Python 进程内运行 daemon 代码——Landlock 锁定后没有第二次 execve，daemon 脚本的磁盘路径无需保持可达，因此 /run 可留在 Landlock 白名单之外；README 将 Landlock/seccomp 的可用性表述为依赖内核支持。
+
+Sources / 来源：[jiuwenbox/src/jiuwenbox/server/runtime/process.py:L1301–L1316](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/src/jiuwenbox/server/runtime/process.py#L1301-L1316), [jiuwenbox/src/jiuwenbox/server/runtime/process.py:L1336–L1355](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/src/jiuwenbox/server/runtime/process.py#L1336-L1355), [jiuwenbox/src/jiuwenbox/server/runtime/process.py:L1055–L1072](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/src/jiuwenbox/server/runtime/process.py#L1055-L1072), [jiuwenbox/README_CN.md:L48–L52](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenbox/README_CN.md#L48-L52)
+
diff --git a/knowledge/repos/jiuwenswarm/components/symphony-orchestration/_index.md b/knowledge/repos/jiuwenswarm/components/symphony-orchestration/_index.md
index 11f532bd..2bee7542 100644
--- a/knowledge/repos/jiuwenswarm/components/symphony-orchestration/_index.md
+++ b/knowledge/repos/jiuwenswarm/components/symphony-orchestration/_index.md
@@ -35,7 +35,7 @@ sources: []
 
 | PR 描述在做什么 | 精确规则 | 第一批 live 源码 |
 |---|---|---|
-| symphony、graph build、图谱构建、fingerprint、能力指纹、evolution、经验演进、experience candidate、… | 入口 | `jiuwenswarm/symphony/adapter.py`、`jiuwenswarm/symphony/build.py`、`jiuwenswarm/symphony/config.py` |
+| symphony、graph build、图谱构建、fingerprint、能力指纹、evolution、经验演进、experience candidate、… | 入口 | `components/agent-runtime/`、`components/gateway-channels/`、`jiuwenswarm/symphony/adapter.py` |
 
 ## 验证入口
 
@@ -52,3 +52,4 @@ sources: []
 - [shared](shared/_index.md)
 - [skill-retrieval](skill-retrieval/_index.md)
 - [Symphony 检索与图谱编排：实现深读](feature-depth-symphony.md)
+- [Symphony orchestration service (jiuwenswarm/symphony/service.py) 基础知识页](knowledge.md)
diff --git a/knowledge/repos/jiuwenswarm/components/symphony-orchestration/feature-symphony.md b/knowledge/repos/jiuwenswarm/components/symphony-orchestration/feature-symphony.md
index 6d962380..dc646e54 100644
--- a/knowledge/repos/jiuwenswarm/components/symphony-orchestration/feature-symphony.md
+++ b/knowledge/repos/jiuwenswarm/components/symphony-orchestration/feature-symphony.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/Symphony-技能编排与分发.md
 feature: "symphony"
 entry_points: ["jiuwenswarm/symphony/service.py"]
-source_globs: ["jiuwenswarm/symphony/service.py", "jiuwenswarm/symphony/*.py"]
+source_globs: ["jiuwenswarm/symphony/service.py", "jiuwenswarm/symphony/*.py", "jiuwenswarm/agents/harness/common/rails/skill_retrieval_prompt_rail.py", "jiuwenswarm/server/runtime/skill/skill_manager.py", "jiuwenswarm/channels/web/frontend/src/components/SkillGraphPanel/index.tsx", "jiuwenswarm/channels/web/frontend/src/components/SkillGraphPanel/skillGraphLayout.ts", "jiuwenswarm/channels/web/frontend/src/components/SkillGraphPanel/SkillGraphPanel.css", "jiuwenswarm/channels/web/frontend/src/components/SkillPanel/symphonyGraphAction.ts", "jiuwenswarm/channels/web/frontend/src/components/SkillPanel/useSymphonyGraph.ts", "jiuwenswarm/agents/harness/common/tools/skill_retrieval_toolkits.py", "jiuwenswarm/channels/web/frontend/src/components/SkillPanel/skillRetrievalStatus.ts", "jiuwenswarm/channels/web/frontend/src/components/SkillPanel/useRetrievalIndexBuild.ts", "jiuwenswarm/server/runtime/agent_adapter/interface_deep.py", "jiuwenswarm/agents/swarm/providers/evolution_rails.py", "jiuwenswarm/symphony/build.py", "jiuwenswarm/symphony/adapter.py", "jiuwenswarm/symphony/experience.py", "jiuwenswarm/agents/harness/common/rails/symphony/orchestration_rail.py", "jiuwenswarm/symphony/graph_state.py", "jiuwenswarm/symphony/graph_storage.py", "jiuwenswarm/symphony/llm.py", "jiuwenswarm/symphony/shared/llm_payload.py", "jiuwenswarm/agents/harness/common/rails/symphony/__init__.py", "jiuwenswarm/symphony/shared/rich_compat.py", "jiuwenswarm/symphony/shared/__init__.py", "jiuwenswarm/symphony/shared/storage.py", "jiuwenswarm/agents/harness/common/tools/symphony_toolkits.py", "jiuwenswarm/symphony/skill_retrieval/__init__.py", "jiuwenswarm/symphony/skill_retrieval/runtime.py", "jiuwenswarm/symphony/shared/profiling.py", "jiuwenswarm/symphony/shared/tags.py"]
 ---
 
 # Symphony 检索与图谱编排 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/symphony-orchestration/knowledge.md b/knowledge/repos/jiuwenswarm/components/symphony-orchestration/knowledge.md
new file mode 100644
index 00000000..4ea133b3
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/symphony-orchestration/knowledge.md
@@ -0,0 +1,43 @@
+---
+title: "Symphony orchestration service (jiuwenswarm/symphony/service.py) 基础知识页"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/symphony/service.py:L210-L224, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/symphony/service.py:L636-L672, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/symphony/service.py:L449-L472, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/symphony/service.py:L515-L533, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/symphony/service.py:L937-L998, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/symphony/service.py:L80-L84, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/symphony/config.py:L12-L33, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/symphony/config.py:L112-L151, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/symphony/config.py:L240-L273, "openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/Symphony-技能编排与分发.md:L93-L99", openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/symphony/service.py:L1188-L1214, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/symphony/service.py:L1252-L1311]
+---
+
+# Symphony orchestration service (jiuwenswarm/symphony/service.py) 基础知识页
+
+<!-- kb:knowledge owner=symphony-orchestration facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**进程内 Symphony 服务的 runtime 管理与构建互斥**
+
+SwarmSymphonyService 是进程级单例（get_swarm_symphony_service），持有并复用 Core 的 SymphonyRuntime：默认模型 runtime 按 graph_dir、mode、top_k、max_depth、min_edge_confidence、evolution 开关与 LLM 签名组成缓存键重建。但服务并非只维护一个 runtime：plan 传入 llm_config 时会创建不带 Flow 的临时 runtime 并在结束后关闭；读取图谱工件时也会构造独立 runtime。缓存键变化时若现有 runtime 已挂 Flow store（单一进程 owner），会拒绝替换，配置变更需重启生效。所有图谱构建经 _build_guard 互斥，同一时刻仅一个构建任务。
+
+Sources / 来源：[jiuwenswarm/symphony/service.py:L210–L224](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/symphony/service.py#L210-L224), [jiuwenswarm/symphony/service.py:L636–L672](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/symphony/service.py#L636-L672), [jiuwenswarm/symphony/service.py:L449–L472](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/symphony/service.py#L449-L472), [jiuwenswarm/symphony/service.py:L515–L533](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/symphony/service.py#L515-L533)
+
+<!-- kb:knowledge owner=symphony-orchestration facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**install_candidate 的重放与校验契约**
+
+install_candidate(request_id, recipe_id, recipe_version, package_id, integrity, skill_manager) 先用 experience_request_id(recipe_id, version) 校验 request_id，不匹配即拒绝。命中已安装时存在短路：内存或 flow 目录 install_receipts 中已有 installed=true 的回执时，直接以 replayed=true 返回并重新 acknowledge 候选，不再走 review_and_prepare_install。否则经 flow.review_and_prepare_install 复核，verdict 非 approved 即失败；调用方传入的 package_id 与 integrity 仅在非空时才与准备结果比对，之后还做完整性校验与 artifact 目录位置检查。
+
+Sources / 来源：[jiuwenswarm/symphony/service.py:L937–L998](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/symphony/service.py#L937-L998), [jiuwenswarm/symphony/service.py:L80–L84](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/symphony/service.py#L80-L84)
+
+<!-- kb:knowledge owner=symphony-orchestration facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**config.yaml symphony 段的加载、默认值与归一化**
+
+load_symphony_config 从 get_config() 读取 config.yaml 的 symphony 段并经 symphony_config_from_dict 归一化：默认 symphony.enabled=false、evolution 关闭、orchestration mode="fast"、top_k=3、max_depth=4、min_edge_confidence=0.5；paths.skills_root/graph_dir 缺省落在工作区 skills 与 symphony/graph；evolution.flow.enabled 缺省时回退旧位置 evolution.enabled。数值归一化注意：_positive_int 对可解析的非正整数取 max(1, parsed)（如 top_k=0 变为 1，而不是回退默认 3），仅解析失败才用默认；float 阈值被夹取到 [0,1]。
+
+Sources / 来源：[jiuwenswarm/symphony/config.py:L12–L33](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/symphony/config.py#L12-L33), [jiuwenswarm/symphony/config.py:L112–L151](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/symphony/config.py#L112-L151), [jiuwenswarm/symphony/config.py:L240–L273](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/symphony/config.py#L240-L273)
+
+<!-- kb:knowledge owner=symphony-orchestration facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**编排工具与 Web 图谱载荷中的技能包展示**
+
+功能文档把 symphony_read_graph、symphony_refresh_graph、symphony_compose_graph 归为技能编排工具（查图谱状态、刷新图谱、生成执行图）。服务端 graph() 通过 _web_graph_payload 把能力图改写为 Web UI 形态：能力 id 映射为 skill:/capability: 引用，被禁用技能按规范化名称从 capabilities/nodes/edges 中过滤，并扫描工作区 SkillPacks 生成 pack 节点与 contains 边。两个已知边界：包扫描在 try 块内逐项追加、异常仅被吞掉，失败时可能保留已追加的部分包数据而非干净回退；不在主图中的包成员会被新建节点加入，绕过了上述禁用过滤。
+
+Sources / 来源：[docs/zh/Symphony-技能编排与分发.md:L93–L99](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/docs/zh/Symphony-%E6%8A%80%E8%83%BD%E7%BC%96%E6%8E%92%E4%B8%8E%E5%88%86%E5%8F%91.md#L93-L99), [jiuwenswarm/symphony/service.py:L1188–L1214](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/symphony/service.py#L1188-L1214), [jiuwenswarm/symphony/service.py:L1252–L1311](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/symphony/service.py#L1252-L1311)
+
diff --git a/knowledge/repos/jiuwenswarm/components/tui-client/_index.md b/knowledge/repos/jiuwenswarm/components/tui-client/_index.md
index 884ffb9b..35d0adb0 100644
--- a/knowledge/repos/jiuwenswarm/components/tui-client/_index.md
+++ b/knowledge/repos/jiuwenswarm/components/tui-client/_index.md
@@ -32,3 +32,5 @@ sources: []
 | PR 描述在做什么 | 精确规则 | 第一批 live 源码 |
 |---|---|---|
 | tui client | 入口 | `jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/autofix-pr.ts`、`jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/autofix-pr.watch.ts`、`jiuwenswarm/channels/tui/frontend/src/index.ts` |
+
+- [tui-client：CliPiAppState 应用状态中枢（app-state.ts）](knowledge.md)
diff --git a/knowledge/repos/jiuwenswarm/components/tui-client/feature-autofix.md b/knowledge/repos/jiuwenswarm/components/tui-client/feature-autofix.md
index 1cebc3b1..2317af3c 100644
--- a/knowledge/repos/jiuwenswarm/components/tui-client/feature-autofix.md
+++ b/knowledge/repos/jiuwenswarm/components/tui-client/feature-autofix.md
@@ -11,7 +11,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/自动修复PR.md
 feature: "autofix"
 entry_points: ["jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/autofix-pr.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/autofix-pr.watch.ts"]
-source_globs: ["jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/autofix-pr*.ts"]
+source_globs: ["jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/autofix-pr*.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/autofix-pr.prompts.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/autofix-pr.status.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/autofix-pr.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/autofix-pr.watch.ts"]
 ---
 
 # 已有 PR 自动修复的命令、轮询与权限边界
diff --git a/knowledge/repos/jiuwenswarm/components/tui-client/feature-tui.md b/knowledge/repos/jiuwenswarm/components/tui-client/feature-tui.md
index 4104375e..dbb93c96 100644
--- a/knowledge/repos/jiuwenswarm/components/tui-client/feature-tui.md
+++ b/knowledge/repos/jiuwenswarm/components/tui-client/feature-tui.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/TUI使用指南.md
 feature: "tui"
 entry_points: ["jiuwenswarm/channels/tui/frontend/src/index.ts"]
-source_globs: ["jiuwenswarm/channels/tui/frontend/src/index.ts", "jiuwenswarm/channels/tui/*"]
+source_globs: ["jiuwenswarm/channels/tui/frontend/src/index.ts", "jiuwenswarm/channels/tui/*", "jiuwenswarm/gateway/routing/agent_request_timeout.py", "jiuwenswarm/server/runtime/gateway_adapter/harmonyos_adapter.py", "jiuwenswarm/channels/tui/frontend/src/ui/app-screen.ts", "jiuwenswarm/server/runtime/gateway_adapter/memory_adapter.py", "jiuwenswarm/agents/harness/common/memory_rpc.py", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/memory.ts", "jiuwenswarm/channels/tui/frontend/src/ui/memory-view.ts", "jiuwenswarm/server/runtime/agent_adapter/statusline_setup_agent.py", "jiuwenswarm/gateway/channel_manager/tui/tui_connect.py", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/chrome.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/collapse.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/color.ts", "jiuwenswarm/channels/tui/frontend/src/core/attachments.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/auto-harness-issue-fix.ts", "jiuwenswarm/channels/tui/frontend/src/app-state.ts", "jiuwenswarm/channels/tui/frontend/src/ui/components/messages/content-components.ts", "jiuwenswarm/channels/tui/frontend/src/ui/components/checkbox-list.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/auto-harness.ts", "jiuwenswarm/channels/tui/frontend/src/core/modes.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/clipboard.ts", "jiuwenswarm/server/runtime/session/project_store.py", "jiuwenswarm/channels/tui/frontend/src/core/commands/helpers.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/config.ts", "jiuwenswarm/common/config_panel/tui_models_handlers.py", "jiuwenswarm/channels/tui/frontend/src/core/tui-config-store.ts", "jiuwenswarm/channels/tui/frontend/src/core/compression-formatters.ts", "jiuwenswarm/channels/tui/frontend/src/core/event-handlers.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/context.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/copy.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/debug.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/diff.ts", "jiuwenswarm/channels/tui/frontend/src/ui/components/messages/diff-component.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/evolve.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/export.ts", "jiuwenswarm/channels/tui/frontend/src/core/utils/editor.ts", "jiuwenswarm/channels/tui/frontend/src/core/final-content.ts", "jiuwenswarm/channels/tui/frontend/src/core/history-parser.ts", "jiuwenswarm/channels/tui/frontend/src/ui/components/messages/history-entry.ts", "jiuwenswarm/channels/tui/frontend/src/ui/components/messages/presentation-rules.ts", "jiuwenswarm/channels/tui/frontend/src/ui/components/messages/render-compact-entry.ts", "jiuwenswarm/channels/tui/frontend/src/ui/components/messages/render-detailed-entry.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/hooks.ts", "jiuwenswarm/channels/tui/frontend/src/ui/components/messages/meta-components.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/init.prompts.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/init.ts", "jiuwenswarm/channels/tui/frontend/src/ui/keymap.ts", "jiuwenswarm/channels/tui/frontend/src/core/keybindings/actions.ts", "jiuwenswarm/channels/tui/frontend/src/core/keybindings/defaultBindings.ts", "jiuwenswarm/channels/tui/frontend/src/core/keybindings/reserved.ts", "jiuwenswarm/channels/tui/frontend/src/core/keybindings/resolver.ts", "jiuwenswarm/channels/tui/frontend/src/core/keybindings/store.ts", "jiuwenswarm/channels/tui/frontend/src/core/keybindings/template.ts", "jiuwenswarm/channels/tui/frontend/src/core/keybindings/types.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/keybindings.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/mcp.ts", "jiuwenswarm/channels/tui/frontend/src/ui/components/messages/shared.ts", "jiuwenswarm/gateway/channel_manager/tui/tui_channel.py", "jiuwenswarm/channels/tui/frontend/src/core/pasted-text.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/persist.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/plan.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/plugin.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/recap.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/reload-plugins.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/review.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/sandbox.ts", "jiuwenswarm/channels/tui/frontend/src/ui/screen-layout.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/security-review.ts", "jiuwenswarm/channels/tui/frontend/src/core/session-state.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/branch.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/cancel.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/clear.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/compact.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/session.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/simplify.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/skills.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/types.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/CommandService.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/_placeholder.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/registry.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/status.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/statusline.ts", "jiuwenswarm/channels/tui/frontend/src/core/statusline-runner.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/swarmflow.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/theme.ts", "jiuwenswarm/channels/tui/frontend/src/ui/theme.ts", "jiuwenswarm/channels/tui/frontend/src/ui/components/tools/search-tool-renderers.ts", "jiuwenswarm/channels/tui/frontend/src/ui/components/tools/tool-group-message.ts", "jiuwenswarm/channels/tui/frontend/src/ui/components/tools/tool-kind-utils.ts", "jiuwenswarm/channels/tui/frontend/src/ui/components/tools/tool-line-renderers.ts", "jiuwenswarm/channels/tui/frontend/src/ui/components/tools/tool-render-shared.ts", "jiuwenswarm/channels/tui/frontend/src/core/app-state-helpers.ts", "jiuwenswarm/channels/tui/frontend/src/ui/components/tools/collapsed-tool-group-message.ts", "jiuwenswarm/channels/tui/frontend/src/ui/components/tools/compact-tool-renderers.ts", "jiuwenswarm/channels/tui/frontend/src/ui/components/tools/command-tool-renderers.ts", "jiuwenswarm/channels/tui/frontend/src/ui/components/tools/detailed-tool-renderers.ts", "jiuwenswarm/channels/tui/frontend/src/ui/components/tools/file-tool-renderers.ts", "jiuwenswarm/channels/tui/frontend/src/ui/components/tools/tool-structured-data.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/expand.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/fold.ts", "jiuwenswarm/channels/tui/frontend/src/ui/transcript-entry-selection.ts", "jiuwenswarm/channels/tui/frontend/src/ui/transcript-renderer.ts", "jiuwenswarm/channels/tui/frontend/src/core/transcript-timeline.ts", "jiuwenswarm/channels/tui/frontend/src/core/tui-trusted-dirs-store.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/usage.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/view.ts", "jiuwenswarm/channels/tui/frontend/src/ui/welcome.ts", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/workspace-dir.ts", "jiuwenswarm/channels/tui/frontend/src/core/ws-client.ts"]
 ---
 
 # TUI 对话与命令 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/tui-client/knowledge.md b/knowledge/repos/jiuwenswarm/components/tui-client/knowledge.md
new file mode 100644
index 00000000..5834d52c
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/tui-client/knowledge.md
@@ -0,0 +1,61 @@
+---
+title: "tui-client：CliPiAppState 应用状态中枢（app-state.ts）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/tui/frontend/src/app-state.ts:L259-L269, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/tui/frontend/src/app-state.ts:L1333-L1383, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/tui/frontend/src/app-state.ts:L1101-L1121, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/tui/frontend/src/app-state.ts:L1980-L2050, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/tui/frontend/src/app-state.ts:L733-L766, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/tui/frontend/src/app-state.ts:L1573-L1662, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/tui/frontend/src/app-state.ts:L2264-L2306, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/tui/frontend/src/app-state.ts:L696-L700, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/tui/frontend/src/app-state.ts:L776-L812, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/tui/frontend/src/app-state.ts:L212-L221, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/tui/frontend/src/app-state.ts:L1554-L1570, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/tui/frontend/src/app-state.ts:L396-L409, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/tui/frontend/src/app-state.ts:L2280-L2287, "openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/TUI使用指南.md:L4-L24", "openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/TUI使用指南.md:L48-L57", openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/tui/frontend/src/app-state.ts:L98-L105, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/tui/frontend/src/app-state.ts:L332-L339, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/tui/frontend/src/app-state.ts:L665-L708, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/tui/frontend/src/app-state.ts:L710-L766, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/tui/frontend/src/app-state.ts:L1537-L1547, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/tui/frontend/src/app-state.ts:L1131-L1144]
+---
+
+# tui-client：CliPiAppState 应用状态中枢（app-state.ts）
+
+<!-- kb:knowledge owner=tui-client facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的行为与关联功能**
+
+两类后台能力由本类承载：一是 auto-recap（用户空闲 5 分钟自动回顾，30 秒周期检查，用户发言后状态机重置为 idle）；二是 TUI 侧 PR watch——`startPrWatch(config)` 用注入的 sendMessage/isBusy/isConnected 构造 PrWatchController，轮次消息以 `logAsUser: false` 发送，watch 结束的 onStopped 回调清除运行内自动批准。另有 /btw 侧问覆盖层：独立于 transcript 渲染的 overlay 带(history/index/total)，支持前后切换与删除当前条目，用户发送新消息时整批清除。team 模式下 SwarmFlow 后台 run 被计入 cancellableWork，使 Esc/Ctrl+C 在 leader round 收尾后仍能中止后台 run。
+
+Sources / 来源：[jiuwenswarm/channels/tui/frontend/src/app-state.ts:L259–L269](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/tui/frontend/src/app-state.ts#L259-L269), [jiuwenswarm/channels/tui/frontend/src/app-state.ts:L1333–L1383](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/tui/frontend/src/app-state.ts#L1333-L1383), [jiuwenswarm/channels/tui/frontend/src/app-state.ts:L1101–L1121](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/tui/frontend/src/app-state.ts#L1101-L1121), [jiuwenswarm/channels/tui/frontend/src/app-state.ts:L1980–L2050](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/tui/frontend/src/app-state.ts#L1980-L2050)
+
+<!-- kb:knowledge owner=tui-client facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**生命周期与后端出口**
+
+生命周期为构造 → start() → stop()（清理各计时器、拒绝未决本地提问、退订并断开 WS）。对后端两类出口：request(method, params, timeoutMs) 走 requestAgentServer，默认 30000ms 超时，请求期间记录 activeCommandRequestId 供 Ctrl+C 立即取消，完成后清理；sendEventOnly 返回生成的请求 id，若启动会话创建未完成则排队到该 Promise 之后发送。sendMessage 在连接断开时返回 null；发送前用 JSON.stringify(...).length 与 7*1024*1024 比较——计量的是字符串长度而非字节数，且该估算不含 sendEventOnly 随后附加的 id、session_id 与路径字段；非 team 模式且流未结束时先发 chat.interrupt(cancel) 再 chat.send。
+
+Sources / 来源：[jiuwenswarm/channels/tui/frontend/src/app-state.ts:L733–L766](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/tui/frontend/src/app-state.ts#L733-L766), [jiuwenswarm/channels/tui/frontend/src/app-state.ts:L1573–L1662](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/tui/frontend/src/app-state.ts#L1573-L1662), [jiuwenswarm/channels/tui/frontend/src/app-state.ts:L2264–L2306](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/tui/frontend/src/app-state.ts#L2264-L2306)
+
+<!-- kb:knowledge owner=tui-client facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**配置读取与解析规则**
+
+构造时 loadTuiConfig 的 theme 字段覆盖当前主题（所示片段仅见 setCurrentThemeName 调用，未见落盘逻辑）。WS 连接建立后 fetchModelInfo 用 Promise.allSettled 并发 config.get / models.list / memory.status：config.get 被拒时 config 取 {} 并继续按默认值处理，而非进入外层 catch。解析规则：preferred_language 仅 trim+小写后等于 "en" 才为 en，其余一律 zh；skill_evolution 接受布尔 true 或 trim+小写后的 "true"/"1"/"yes"/"on"/"enabled"，未知或缺失保持关闭；auto_recap_enabled 仅当严格不等于字符串 "false" 时视为开启（默认 true），并据此启停 auto-recap 定时器。
+
+Sources / 来源：[jiuwenswarm/channels/tui/frontend/src/app-state.ts:L696–L700](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/tui/frontend/src/app-state.ts#L696-L700), [jiuwenswarm/channels/tui/frontend/src/app-state.ts:L776–L812](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/tui/frontend/src/app-state.ts#L776-L812), [jiuwenswarm/channels/tui/frontend/src/app-state.ts:L212–L221](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/tui/frontend/src/app-state.ts#L212-L221)
+
+<!-- kb:knowledge owner=tui-client facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**请求路径与模型注入的取舍**
+
+Inference / 设计推断（非作者历史意图）：
+
+远程模式的路径隔离是有条件的：仅当 isRemote 与 remoteProjectDir 均为真值时，请求才改用服务器侧目录作为 project_dir/cwd 且不发送 trusted_dirs；任一不满足则回退本地 project_dir/cwd 与可信目录列表。agentos 备份模型选择请求级注入而非全局切换：chat.send 注入 model_name 时优先用后端 model_key（model_name#global_idx）以精确命中同名 agentos 条目，缺 key 才回退纯名（同名会被解析到 defaults，仅作兼容兜底）；setModel 切回 defaults 时清空注入字段，启动默认模型路由保持不变。
+
+Sources / 来源：[jiuwenswarm/channels/tui/frontend/src/app-state.ts:L1554–L1570](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/tui/frontend/src/app-state.ts#L1554-L1570), [jiuwenswarm/channels/tui/frontend/src/app-state.ts:L396–L409](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/tui/frontend/src/app-state.ts#L396-L409), [jiuwenswarm/channels/tui/frontend/src/app-state.ts:L2280–L2287](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/tui/frontend/src/app-state.ts#L2280-L2287)
+
+<!-- kb:knowledge owner=tui-client facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**文档验收与启动幂等**
+
+使用指南开头声明「行为以仓库代码为准」，并记录多窗口同 --session 启动会被 Gateway 拒绝（SESSION_IN_USE）、显式 id 的 session.create 幂等且在 connection.ack 后由 initializeBootSession 放行、重连只执行一次；代码侧有对应机制：bootSessionHandled 幂等守卫注释（重连/重发不重试），以及启动期 "already active in another window" 瞬时错误识别函数与 100–800ms 重试延迟表常量——但所示片段只包含常量与识别函数，未展示执行重试的调用循环，实际重试次数不能据此确认。
+
+Sources / 来源：[docs/zh/TUI使用指南.md:L4–L24](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/docs/zh/TUI%E4%BD%BF%E7%94%A8%E6%8C%87%E5%8D%97.md#L4-L24), [docs/zh/TUI使用指南.md:L48–L57](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/docs/zh/TUI%E4%BD%BF%E7%94%A8%E6%8C%87%E5%8D%97.md#L48-L57), [jiuwenswarm/channels/tui/frontend/src/app-state.ts:L98–L105](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/tui/frontend/src/app-state.ts#L98-L105), [jiuwenswarm/channels/tui/frontend/src/app-state.ts:L332–L339](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/tui/frontend/src/app-state.ts#L332-L339)
+
+<!-- kb:knowledge owner=tui-client facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**CliPiAppState 的职责边界与生命周期**
+
+`CliPiAppState`（app-state.ts）是 TUI 前端的中央客户端状态类：它持有 WebSocket 客户端（`WsClient`）与会话、转录条目、流式状态、工具执行、team/workflow 等私有字段，通过 `onChange`/`getSnapshot` 对外暴露快照。构造函数注入 `wsClient` 与可选的 CLI 会话参数及监督端口（`supervision?.handoffPort` 等，缺省回退非托管实现）；`start()` 订阅连接状态与帧回调、调用 `wsClient.connect()` 并启动状态栏轮询，`stop()` 依次通知 stop 订阅器、reject 未决本地问题、清理各定时器并断开连接。/switch 等公共契约端口（Handoff/TaskLifecycle/Reauthentication/UiLifecycle）既可在构造时注入，也可由 index.ts 通过 `setSupervisionPorts` 回填；未注入时 `getCommandContext` 对 `checkHandoff` 回退到 `NOT_SUPERVISED` 结果。注意 `getSnapshot` 中 `entries`、`toolExecutions`、workflow 嵌套对象为浅拷贝，内部对象引用仍与状态共享。
+
+Sources / 来源：[jiuwenswarm/channels/tui/frontend/src/app-state.ts:L665–L708](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/tui/frontend/src/app-state.ts#L665-L708), [jiuwenswarm/channels/tui/frontend/src/app-state.ts:L710–L766](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/tui/frontend/src/app-state.ts#L710-L766), [jiuwenswarm/channels/tui/frontend/src/app-state.ts:L1537–L1547](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/tui/frontend/src/app-state.ts#L1537-L1547), [jiuwenswarm/channels/tui/frontend/src/app-state.ts:L1131–L1144](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/tui/frontend/src/app-state.ts#L1131-L1144)
+
diff --git a/knowledge/repos/jiuwenswarm/components/web-frontend/_index.md b/knowledge/repos/jiuwenswarm/components/web-frontend/_index.md
index 1e8b10e2..430b2d95 100644
--- a/knowledge/repos/jiuwenswarm/components/web-frontend/_index.md
+++ b/knowledge/repos/jiuwenswarm/components/web-frontend/_index.md
@@ -105,3 +105,14 @@ sources: []
 - [计划模式与多入口切换限制：实现深读](feature-depth-plan-mode.md)
 - [会话产物列表、预览与下载：实现深读](feature-depth-artifacts.md)
 - [语音输入、回复朗读与停止：实现深读](feature-depth-speech-interaction.md)
+- [IDE Webview 会话统计栏与每轮迷你图（chat.html）](feature-chat-session-stats-dashboard.md)
+- [代码模式分支选择器（CodeBranchSelector）](feature-code-mode-branch-selector.md)
+- [代码模式提交/推送对话框（CodeCommitPushControl）](feature-code-mode-commit-push.md)
+- [上下文占用指示器（ContextUsageIndicator：环形触发器/悬浮提示/明细弹层）](feature-context-usage-indicator.md)
+- [Vite Dev WS Traffic Logger (/__dev/ws-log)](feature-dev-ws-traffic-logger.md)
+- [前端增量 ESLint 门禁（lint-changed.mjs）](feature-frontend-incremental-lint-gate.md)
+- [Web 通道本机目录/可执行文件选择器（directory_picker）](feature-web-native-directory-picker.md)
+- [会话分享图导出：任务注册表与无头渲染器](feature-share-image-export.md)
+- [Web 资产发布流程（prepare/commit/轮询/提交锁）](feature-web-asset-publish-flow.md)
+- [Web 前端中英双语 i18n 初始化（jiuwenswarm/channels/web/frontend）](feature-web-i18n-zh-en.md)
+- [RSI 自我改进实验页（创建/列表/配置回显）](feature-rsi-experiment-ui.md)
diff --git a/knowledge/repos/jiuwenswarm/components/web-frontend/feature-agent-management.md b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-agent-management.md
index 274755fc..c6f90d51 100644
--- a/knowledge/repos/jiuwenswarm/components/web-frontend/feature-agent-management.md
+++ b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-agent-management.md
@@ -12,7 +12,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/智能体.md
 feature: "agent-management"
 entry_points: ["jiuwenswarm/channels/web/frontend/src/components/AgentManagementPanel/index.tsx", "jiuwenswarm/channels/web/frontend/src/features/agentManagement/client.ts", "jiuwenswarm/channels/web/frontend/src/components/AgentPanel/index.tsx"]
-source_globs: ["jiuwenswarm/channels/web/frontend/src/components/AgentManagementPanel/index.tsx", "jiuwenswarm/channels/web/frontend/src/features/agentManagement/client.ts", "jiuwenswarm/channels/web/frontend/src/components/AgentPanel/index.tsx"]
+source_globs: ["jiuwenswarm/channels/web/frontend/src/components/AgentManagementPanel/index.tsx", "jiuwenswarm/channels/web/frontend/src/features/agentManagement/client.ts", "jiuwenswarm/channels/web/frontend/src/components/AgentPanel/index.tsx", "jiuwenswarm/channels/web/frontend/src/components/AgentAvatar/index.tsx", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/MessageItem.tsx", "jiuwenswarm/channels/web/frontend/src/components/AgentManagementPanel/CatalogPage.tsx", "jiuwenswarm/channels/web/frontend/src/components/AgentManagementPanel/DefinitionCard.tsx", "jiuwenswarm/channels/web/frontend/src/components/AgentManagementPanel/DefinitionDetailPage.tsx", "jiuwenswarm/channels/web/frontend/src/components/AgentManagementPanel/DefinitionFilePreview.tsx", "jiuwenswarm/channels/web/frontend/src/components/AgentManagementPanel/AgentGroupUploadDialog.tsx", "jiuwenswarm/channels/web/frontend/src/components/AgentManagementPanel/AgentUploadDialog.tsx", "jiuwenswarm/channels/web/frontend/src/components/AgentManagementPanel/AgentEditor.tsx", "jiuwenswarm/scripts/generate-agent-folders.js", "jiuwenswarm/scripts/watch-folders.js", "jiuwenswarm/server/runtime/extension_package_manager.py", "jiuwenswarm/channels/web/frontend/src/components/AgentManagementPanel/GroupCard.tsx", "jiuwenswarm/channels/web/frontend/src/components/AgentManagementPanel/GroupCatalogPage.tsx", "jiuwenswarm/channels/web/frontend/src/components/AgentManagementPanel/AgentGroupDetailPage.tsx", "jiuwenswarm/channels/web/frontend/src/components/AgentManagementPanel/AgentGroupEditor.tsx", "jiuwenswarm/channels/web/frontend/src/components/AgentManagementPanel/AgentGroupMemberPicker.tsx", "jiuwenswarm/resources/agent/workspace/skills/agent-group-creator/scripts/register_group.py", "jiuwenswarm/channels/web/frontend/src/components/AgentManagementPanel/SelectionPagination.tsx", "jiuwenswarm/channels/web/frontend/src/components/AgentManagementPanel/AgentTagPicker.tsx", "jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/init_template.py", "jiuwenswarm/resources/agent/workspace/skills/agent-creator/scripts/register_template.py", "jiuwenswarm/server/runtime/agent_config_service.py", "jiuwenswarm/channels/web/app_web.py", "jiuwenswarm/server/runtime/skill/skill_manager.py", "jiuwenswarm/channels/web/frontend/vite.config.ts", "jiuwenswarm/channels/web/frontend/src/components/AgentManagementPanel/useDialogFocusTrap.ts", "jiuwenswarm/channels/web/frontend/src/components/ui/FilePreviewPanel/FilePreviewPanel.css", "jiuwenswarm/channels/web/frontend/src/components/ui/FilePreviewPanel/FilePreviewPanel.tsx", "jiuwenswarm/channels/web/frontend/src/components/ui/FilePreviewPanel/filePreviewShared.ts", "jiuwenswarm/channels/web/frontend/src/components/ui/FilePreviewPanel/FilePreviewTree.tsx", "jiuwenswarm/server/runtime/agent_adapter/interface.py", "jiuwenswarm/resources/agent/workspace/skills/plugin-creator/scripts/register_plugin.py", "jiuwenswarm/channels/tui/frontend/src/core/commands/builtins/agents.ts", "jiuwenswarm/channels/tui/frontend/src/ui/app-screen.ts", "jiuwenswarm/channels/web/frontend/src/components/AgentPanel/FileViewer.tsx", "jiuwenswarm/channels/web/frontend/src/stores/agentCatalogStore.ts", "jiuwenswarm/channels/web/frontend/src/stores/agentGroupCatalogSeed.ts", "jiuwenswarm/channels/web/frontend/src/hooks/useWebSocket.ts", "jiuwenswarm/channels/web/frontend/src/features/agentManagement/groupClient.ts", "jiuwenswarm/channels/web/frontend/src/features/agentManagement/port.ts", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/InputArea.tsx", "jiuwenswarm/channels/web/frontend/src/features/agentManagement/adapter.ts", "jiuwenswarm/channels/web/frontend/src/features/agentManagement/limits.ts", "jiuwenswarm/channels/web/frontend/src/features/agentManagement/tagOptions.ts", "jiuwenswarm/channels/web/frontend/src/features/agentManagement/pendingInstallQueue.ts", "jiuwenswarm/channels/web/frontend/src/features/agentManagement/upload.ts", "jiuwenswarm/channels/web/frontend/src/features/agentIdentity.ts", "jiuwenswarm/channels/web/frontend/src/features/catalogCache.ts", "jiuwenswarm/channels/web/frontend/src/features/equipmentListRequest.ts", "jiuwenswarm/channels/web/frontend/src/features/equipmentMarketplace.ts", "jiuwenswarm/channels/web/frontend/src/features/historyFilePreview.ts", "jiuwenswarm/channels/web/frontend/src/features/agentManagement/selection.ts"]
 ---
 
 # 智能体资产管理与工作区浏览的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/web-frontend/feature-artifacts.md b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-artifacts.md
index 4476ce96..86015e04 100644
--- a/knowledge/repos/jiuwenswarm/components/web-frontend/feature-artifacts.md
+++ b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-artifacts.md
@@ -12,7 +12,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/AGENTS.md
 feature: "artifacts"
 entry_points: ["jiuwenswarm/channels/web/frontend/src/components/ArtifactsPanel/index.tsx", "jiuwenswarm/channels/web/frontend/src/components/ArtifactsPanel/artifactCollection.ts", "jiuwenswarm/channels/web/frontend/src/components/ArtifactsPanel/filePreviewModel.ts"]
-source_globs: ["jiuwenswarm/channels/web/frontend/src/components/ArtifactsPanel/index.tsx", "jiuwenswarm/channels/web/frontend/src/components/ArtifactsPanel/artifactCollection.ts", "jiuwenswarm/channels/web/frontend/src/components/ArtifactsPanel/filePreviewModel.ts"]
+source_globs: ["jiuwenswarm/channels/web/frontend/src/components/ArtifactsPanel/index.tsx", "jiuwenswarm/channels/web/frontend/src/components/ArtifactsPanel/artifactCollection.ts", "jiuwenswarm/channels/web/frontend/src/components/ArtifactsPanel/filePreviewModel.ts", "jiuwenswarm/channels/web/frontend/src/components/ArtifactsPanel/codeLanguageExtensions.ts", "jiuwenswarm/channels/web/frontend/src/components/ArtifactsPanel/codeLanguages.ts", "jiuwenswarm/channels/web/frontend/src/components/ArtifactsPanel/SpreadsheetPreview.tsx", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/MessageItem.tsx", "jiuwenswarm/gateway/channel_manager/web/container_file_http.py", "jiuwenswarm/channels/web/frontend/src/utils/fileDownloadDedup.ts", "jiuwenswarm/channels/web/frontend/vite.config.ts", "jiuwenswarm/channels/web/frontend/src/components/FileIcon/fileIconModel.ts", "jiuwenswarm/channels/web/frontend/src/components/FileIcon/index.tsx", "jiuwenswarm/channels/web/frontend/src/components/ArtifactsPanel/officeFontStack.ts", "jiuwenswarm/channels/web/frontend/src/components/ArtifactsPanel/ooxmlArchiveLimits.ts", "jiuwenswarm/channels/web/frontend/src/components/ArtifactsPanel/pptxPresentationParser.ts", "jiuwenswarm/channels/web/frontend/src/components/ArtifactsPanel/pptxPreviewModel.ts", "jiuwenswarm/channels/web/frontend/src/components/ArtifactsPanel/pptxPreview.worker.ts", "jiuwenswarm/channels/web/frontend/src/components/ArtifactsPanel/spreadsheetWorkbookParser.ts", "jiuwenswarm/channels/web/frontend/src/components/ArtifactsPanel/spreadsheetPreviewModel.ts", "jiuwenswarm/channels/web/frontend/src/components/ArtifactsPanel/spreadsheetPreview.worker.ts", "jiuwenswarm/server/runtime/gateway_adapter/workspace_file_adapter.py", "jiuwenswarm/agents/harness/common/tools/verified_download_assets.py", "jiuwenswarm/channels/web/frontend/src/components/ArtifactsPanel/CodePreview.tsx", "jiuwenswarm/channels/web/frontend/src/components/ArtifactsPanel/DocxPreview.tsx", "jiuwenswarm/channels/web/frontend/src/components/ArtifactsPanel/ArtifactExpandedPanel.tsx", "jiuwenswarm/channels/web/frontend/src/components/ArtifactsPanel/PresentationPreview.tsx", "jiuwenswarm/channels/web/frontend/src/components/ArtifactsPanel/FilePreview.tsx", "jiuwenswarm/channels/web/frontend/src/features/desktopBrowserFile.ts", "jiuwenswarm/channels/web/app_web.py", "jiuwenswarm/agents/harness/common/tools/web_file_download.py", "jiuwenswarm/channels/web/frontend/src/components/ui/FilePreviewPanel/FilePreviewContent.tsx", "jiuwenswarm/channels/web/frontend/src/components/ui/FilePreviewPanel/FilePreviewIcon.tsx", "jiuwenswarm/channels/web/frontend/src/components/ArtifactsPanel/chartGeometry.ts"]
 ---
 
 # 会话产物列表、预览与下载的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/web-frontend/feature-chat-session-stats-dashboard.md b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-chat-session-stats-dashboard.md
new file mode 100644
index 00000000..d86627eb
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-chat-session-stats-dashboard.md
@@ -0,0 +1,62 @@
+---
+title: "IDE Webview 会话统计栏与每轮迷你图（chat.html）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/shared-webview/chat.html:L4453-L4524, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/shared-webview/chat.html:L4475-L4489, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/shared-webview/chat.html:L4492-L4524, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/shared-webview/chat.html:L4495-L4521, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/shared-webview/chat.html:L4602-L4628, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/shared-webview/chat.html:L4475-L4477, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/shared-webview/chat.html:L4494-L4496, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/shared-webview/chat.html:L4626-L4628, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/shared-webview/chat.html:L4503-L4516, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/shared-webview/chat.html:L4517-L4521, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/ide/packages/shared-webview/chat.html:L4691-L4697]
+feature: "chat-session-stats-dashboard"
+entry_points: ["jiuwenswarm/channels/ide/packages/shared-webview/chat.html"]
+source_globs: ["jiuwenswarm/channels/ide/packages/shared-webview/chat.html"]
+---
+
+# IDE Webview 会话统计栏与每轮迷你图（chat.html）
+
+<!-- kb:knowledge owner=feature-chat-session-stats-dashboard facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**无所示验证入口**
+
+所提供的行范围内不包含任何测试或验证代码，无法从该片段确认统计栏与迷你图的测试覆盖情况。
+
+Sources / 来源：[jiuwenswarm/channels/ide/packages/shared-webview/chat.html:L4453–L4524](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/shared-webview/chat.html#L4453-L4524)
+
+<!-- kb:knowledge owner=feature-chat-session-stats-dashboard facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**渲染入口与生命周期**
+
+该片段的入口是三个页面内函数：`renderStatsBar` 将拼好的 HTML 字符串直接赋给容器的 `innerHTML` 并加 `visible` class；`renderMiniCharts` 同样直接写 `innerHTML`（不足 2 轮时直接 return）；`toggleCharts` 翻转 `state.chartsCollapsed` 并重渲染。它们直接操作 DOM，不返回值，片段中也未展示对外错误契约。
+
+Sources / 来源：[jiuwenswarm/channels/ide/packages/shared-webview/chat.html:L4475–L4489](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/shared-webview/chat.html#L4475-L4489), [jiuwenswarm/channels/ide/packages/shared-webview/chat.html:L4492–L4524](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/shared-webview/chat.html#L4492-L4524)
+
+<!-- kb:knowledge owner=feature-chat-session-stats-dashboard facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**状态驱动的纯渲染层**
+
+统计栏与迷你图是从 `state.sessionStats`（含 `turnTokens`、`turnDurations`、`ttfts`、`outcomes` 等数组）和 `state.todoStats` 读取数据渲染的展示层；数据如何写入这些 state 的路径未在片段中展示。`clearMessages` 承担重置职责：将 `sessionStats`、`todoStats` 归零、清空 `mini-charts` 容器并把 `chartsCollapsed` 置回 true。
+
+Sources / 来源：[jiuwenswarm/channels/ide/packages/shared-webview/chat.html:L4495–L4521](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/shared-webview/chat.html#L4495-L4521), [jiuwenswarm/channels/ide/packages/shared-webview/chat.html:L4602–L4628](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/shared-webview/chat.html#L4602-L4628)
+
+<!-- kb:knowledge owner=feature-chat-session-stats-dashboard facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**运行时 state 控制的显示开关**
+
+所示片段不含外部配置项；显示行为由 state 决定。图表折叠按钮仅在 `s.totalTurns >= 2` 时渲染，`renderMiniCharts` 在 `totalTurns < 2` 时直接返回；`clearMessages` 结束时把 `chartsCollapsed` 重置为 true。
+
+Sources / 来源：[jiuwenswarm/channels/ide/packages/shared-webview/chat.html:L4475–L4477](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/shared-webview/chat.html#L4475-L4477), [jiuwenswarm/channels/ide/packages/shared-webview/chat.html:L4494–L4496](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/shared-webview/chat.html#L4494-L4496), [jiuwenswarm/channels/ide/packages/shared-webview/chat.html:L4626–L4628](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/shared-webview/chat.html#L4626-L4628)
+
+<!-- kb:knowledge owner=feature-chat-session-stats-dashboard facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**所示片段中的验证手段**
+
+所示 4453–4759 行范围内没有测试或断言代码，统计栏与迷你图的正确性在该片段内仅由运行时守卫体现：折叠按钮仅在 `s.totalTurns >= 2` 时渲染（L4475–L4477），`renderMiniCharts` 在 `totalTurns < 2` 时直接返回（L4494–L4496）。`clearMessages` 中列出了对 `sessionStats` 各数组、`todoStats`、`mini-charts` 容器与 `chartsCollapsed` 的逐项重置操作，可作为新会话时清空展示的对照清单。
+
+Sources / 来源：[jiuwenswarm/channels/ide/packages/shared-webview/chat.html:L4475–L4477](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/shared-webview/chat.html#L4475-L4477), [jiuwenswarm/channels/ide/packages/shared-webview/chat.html:L4494–L4496](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/shared-webview/chat.html#L4494-L4496), [jiuwenswarm/channels/ide/packages/shared-webview/chat.html:L4602–L4628](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/shared-webview/chat.html#L4602-L4628)
+
+<!-- kb:knowledge owner=feature-chat-session-stats-dashboard facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**归一化最小柱高与纯字符串渲染**
+
+柱高按各轮值相对该序列最大值（Math.max(...values, 1)，分母至少为 1）归一化为百分比，且 Math.max(6, ...) 强制最小 6% 高度，避免零值柱在视觉上不可见。迷你图通过字符串拼接生成 HTML 并整体赋给 innerHTML（该片段另定义了 escapeHtml 但此处未调用）；每个 data-tip 仅在柱状图为 Duration（非 Tokens）且该轮 ttft 非空时才附带 First token 时长。
+
+Sources / 来源：[jiuwenswarm/channels/ide/packages/shared-webview/chat.html:L4503–L4516](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/shared-webview/chat.html#L4503-L4516), [jiuwenswarm/channels/ide/packages/shared-webview/chat.html:L4517–L4521](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/shared-webview/chat.html#L4517-L4521), [jiuwenswarm/channels/ide/packages/shared-webview/chat.html:L4691–L4697](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/ide/packages/shared-webview/chat.html#L4691-L4697)
+
diff --git a/knowledge/repos/jiuwenswarm/components/web-frontend/feature-code-mode-branch-selector.md b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-code-mode-branch-selector.md
new file mode 100644
index 00000000..a53b6074
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-code-mode-branch-selector.md
@@ -0,0 +1,64 @@
+---
+title: "代码模式分支选择器（CodeBranchSelector）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx:L128-L131, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx:L192-L192, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx:L195-L247, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx:L307-L331, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx:L10-L34, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx:L55-L78, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx:L138-L190, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx:L10-L16, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx:L197-L226, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx:L138-L146, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx:L55-L67, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx:L84-L105, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx:L243-L285, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeEnvironmentPanel.tsx:L47-L56]
+feature: "code-mode-branch-selector"
+entry_points: ["jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx"]
+source_globs: ["jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx", "jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeEnvironmentPanel.tsx"]
+---
+
+# 代码模式分支选择器（CodeBranchSelector）
+
+<!-- kb:knowledge owner=feature-code-mode-branch-selector facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**设计取舍**
+
+Inference / 设计推断（非作者历史意图）：
+
+组件仅对 `work_mode === 'code'` 且非默认项目渲染（否则返回 null），把代码模式分支能力与其他项目隔离；这是从 props 判断得出的边界。选择双通道数据（主动 status/probe + liveRepo 增量覆写）换取环境面板实时性，但 currentBranch 有三级回退（liveRepo → status → project.git.branch），可能短暂显示陈旧值（推断）。错误处理以文案映射为主，全部操作共用一个 error 状态，不重试。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx:L128–L131](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx#L128-L131), [jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx:L192–L192](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx#L192-L192)
+
+<!-- kb:knowledge owner=feature-code-mode-branch-selector facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证入口**
+
+组件自身源码中布满 `data-testid` 锚点（如 `code-mode-branch-selector`、`code-mode-branch-trigger` 带 `data-variant='init'|'switch'`、`code-mode-branch-menu`、`code-mode-branch-create-hint`、`code-mode-create-branch-dialog` 系列），并使用 `role='menu'`/`menuitemradio`/`aria-checked` 等可访问性语义，为 UI 测试与交互验证提供了钩子。本输入未包含对应测试文件，无法核实实际测试覆盖。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx:L195–L247](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx#L195-L247), [jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx:L307–L331](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx#L307-L331)
+
+<!-- kb:knowledge owner=feature-code-mode-branch-selector facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**公共入口与操作契约**
+
+组件导出为 `CodeBranchSelector`，接收 `project`、`compact`、`disabled`、`variant`（'default' | 'environment'）与 `liveRepo` 五个 props；当 `project` 缺失、`work_mode !== 'code'` 或 `is_default` 时返回 null（不渲染）。三个写操作——初始化（`gitClient.init(project_id, 'main')`）、切换分支（`gitClient.switchBranch`）、创建分支（`gitClient.createBranch`，起点为当前分支）——成功后更新本地 status 并调用 `loadProjects()`；只读的 status/probe 加载成功路径不调用 `loadProjects()`。错误经 `getErrorMessage` 将 `WebError.code`（如 WORKTREE_DIRTY、GIT_TRANSIENT_STATE、BRANCH_NOT_FOUND、BRANCH_ALREADY_EXISTS、GIT_NOT_FOUND）映射为中文文案，但 `NOT_GIT_REPOSITORY` 例外：加载失败时它转入 notGit 状态而非错误提示。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx:L10–L34](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx#L10-L34), [jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx:L55–L78](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx#L55-L78), [jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx:L138–L190](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx#L138-L190)
+
+<!-- kb:knowledge owner=feature-code-mode-branch-selector facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**可配置项与固定行为**
+
+配置面由五个 props 构成，其中 `project` 直接决定行为：非 code 模式或默认项目既不加载状态也不渲染；`compact`/`variant` 仅切换样式类。`disabled` 并非简单透传：触发按钮将其与 `operating`（初始化按钮）或 `operating || loading || !status`（切换按钮）合并后作为 disabled。初始化分支名硬编码为 `'main'`（`gitClient.init(project.project_id, 'main')`），不接受用户配置。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx:L10–L16](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx#L10-L16), [jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx:L197–L226](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx#L197-L226), [jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx:L138–L146](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx#L138-L146)
+
+<!-- kb:knowledge owner=feature-code-mode-branch-selector facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**渲染边界与双通道状态数据流**
+
+组件只对 `work_mode === 'code'` 且非默认（`is_default`）的项目工作：满足条件才在 `loadStatus` 中发起请求，否则清空状态，且渲染层直接返回 null。状态加载按 `project.git` 的已知程度分流：`git.status === 'ready'` 或 `git.enabled` 时调用 `gitClient.status`，否则先调用 `gitClient.probe`。组件另有第二数据通道：`liveRepo`（由环境面板的 diffWatch 注入）在守卫通过后（liveRepo 与 project 存在、code 模式且非默认项目）更新 `notGit`，并仅在已有 status 时把 `repo.is_git/repo_root/branch/head/transient` 与 `branches.current` 合并进去，不整体替换状态。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx:L55–L67](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx#L55-L67), [jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx:L192–L192](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx#L192-L192), [jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx:L84–L105](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx#L84-L105)
+
+<!-- kb:knowledge owner=feature-code-mode-branch-selector facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的功能行为**
+
+组件覆盖三项 Git 分支操作：目录非 Git 仓库时提供“初始化 Git”按钮（调用 gitClient.init(project_id, 'main') 并刷新项目列表）；在下拉菜单中选中本地分支时调用 gitClient.switchBranch 切换——但当所选分支即当前分支（branch === currentBranch）时仅关闭菜单直接返回，不发起请求；通过“创建并检出新分支”对话框以当前分支为起点调用 gitClient.createBranch。操作成功后更新本地 status 并调用 loadProjects()。写操作入口有条件禁用：仓库处于 transient（合并/变基）或 detached HEAD 时切换与创建按钮禁用（branchWritesBlocked），空仓库（unborn HEAD，有分支名但无 head）时创建入口禁用并提示需先完成首次提交。组件被 CodeEnvironmentPanel 以 variant="environment"、compact 模式嵌入，并注入 diffWatch 的 liveRepo 以增量更新分支显示；liveRepo 不可用时 currentBranch 回退到 status 或 project.git.branch。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx:L128–L131](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx#L128-L131), [jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx:L138–L190](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx#L138-L190), [jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx:L243–L285](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeBranchSelector.tsx#L243-L285), [jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeEnvironmentPanel.tsx:L47–L56](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeEnvironmentPanel.tsx#L47-L56)
+
diff --git a/knowledge/repos/jiuwenswarm/components/web-frontend/feature-code-mode-commit-push.md b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-code-mode-commit-push.md
new file mode 100644
index 00000000..540beb5c
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-code-mode-commit-push.md
@@ -0,0 +1,66 @@
+---
+title: "代码模式提交/推送对话框（CodeCommitPushControl）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L10-L20, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L73-L74, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L139-L142, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L162-L174, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L46-L51, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L79-L82, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L119-L119, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L356-L361, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L121-L131, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L278-L291, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L365-L388, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L198-L205, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L243-L247, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L374-L384, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L407-L420, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L181-L189, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L95-L108, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L228-L233, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L63-L82, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L153-L180, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L133-L145]
+feature: "code-mode-commit-push"
+entry_points: ["jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx"]
+source_globs: ["jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx"]
+---
+
+# 代码模式提交/推送对话框（CodeCommitPushControl）
+
+<!-- kb:knowledge owner=feature-code-mode-commit-push facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**组件接口与依赖的后端调用**
+
+`CodeCommitPushControl` 是一个 React 函数组件，props 包括 `project`、`branch`、`hasChanges`、`filesChanged`、`isGit`、`transient`、`isProcessing`、`variant`（`environment` 或 `review`，决定触发按钮样式）和成功回调 `onSuccess`。它不直接访问网络层，而是通过 `gitClient` 的 `status`、`commit`、`push`、`createBranch` 方法完成全部 Git 操作，从 `gitPublishState` 复用 `GitPublishOperation` 类型、`defaultCommitMessage`、`gitPublishErrorMessage` 与 `remoteNames`。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L10–L20](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx#L10-L20), [jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L73–L74](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx#L73-L74), [jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L139–L142](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx#L139-L142), [jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L162–L174](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx#L162-L174)
+
+<!-- kb:knowledge owner=feature-code-mode-commit-push facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**表单默认值与交互选项**
+
+可配置项均为对话框内表单状态：远程仓库名默认取 `remoteNames(...)[0]`；`includeUnstaged`（提交时是否 stageAll）默认 true；`setUpstream` 默认根据 `status.repo.upstream` 是否存在决定，选择非当前分支时自动置 true。提交信息留空时回退到 `defaultCommitMessage(filesChanged)` 生成的默认消息，输入框 `maxLength=200` 并显示计数；新分支名输入 `maxLength=255`。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L46–L51](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx#L46-L51), [jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L79–L82](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx#L79-L82), [jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L119–L119](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx#L119-L119), [jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L356–L361](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx#L356-L361)
+
+<!-- kb:knowledge owner=feature-code-mode-commit-push facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的操作与守卫条件**
+
+支持三种操作：仅提交、提交并推送、仅推送；提交时可勾选包含未暂存更改（透传为 `stageAll`），推送时可勾选设置上游分支。对话框内可新建并检出分支（unborn HEAD 或仓库处于 transient Git 操作时禁用该入口）。触发按钮在 `isProcessing`、非 Git 仓库或 `transient` 时禁用，并以 `title` 说明原因；提交按钮要求操作含提交时工作区有改动、含推送时已选分支和非空远程。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L121–L131](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx#L121-L131), [jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L278–L291](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx#L278-L291), [jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L365–L388](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx#L365-L388)
+
+<!-- kb:knowledge owner=feature-code-mode-commit-push facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**测试挂载点**
+
+Inference / 设计推断（非作者历史意图）：
+
+组件暴露了密集的 `data-testid` 钩子，覆盖触发按钮（`code-mode-publish-trigger`，带 `data-variant`）、对话框本身、加载态、分支选择/新建、远程选择、提交信息、三种操作单选（`code-mode-publish-operation` 带 `data-variant`）、选项复选框、错误区和提交按钮，以及成功 toast（`code-mode-publish-toast`）。这些命名稳定的选择器即为端到端/组件测试的入口；本次输入未包含对应测试文件，具体用例无法确认。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L198–L205](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx#L198-L205), [jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L243–L247](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx#L243-L247), [jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L374–L384](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx#L374-L384), [jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L407–L420](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx#L407-L420)
+
+<!-- kb:knowledge owner=feature-code-mode-commit-push facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**两阶段提交的失败恢复与关闭守卫的不对称**
+
+Inference / 设计推断（非作者历史意图）：
+
+commit 与 push 在前端拆成两次串行请求而非单一后端操作：当 `commit_push` 中提交成功而推送失败时，组件保留已提交的 hash，仍触发 `onSuccess` 刷新，把操作切回 `push` 并显示「提交已成功（hash），但推送失败」的错误，让用户只需重试推送（推断：以多次往返换取部分失败的可恢复性）。关闭守卫存在不对称：Escape 处理在 `submitting` 或 `creatingBranch` 时阻止关闭（建分支面板打开时 Escape 仅收起该面板），但遮罩点击关闭只检查 `submitting`，因此 `creatingBranch` 期间仍可能通过点击遮罩关闭对话框。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L181–L189](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx#L181-L189), [jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L95–L108](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx#L95-L108), [jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L228–L233](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx#L228-L233)
+
+<!-- kb:knowledge owner=feature-code-mode-commit-push facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**组件职责与数据/控制流**
+
+`CodeCommitPushControl` 是一个自管理打开状态的 React 展示组件：对话框的 `open` 由内部 `useState` 维护，外部只通过 props 传入 `project`、`branch`、`hasChanges`、`isGit`、`transient`、`isProcessing`、`variant` 等上下文和 `onSuccess` 回调，不接收打开/关闭控制。数据流为：打开时（`open` 变为 true 的 effect）调用 `gitClient.status(project.project_id)` 拉取仓库状态，并据此初始化分支、远程、`setUpstream` 与默认操作类型（脏工作区且非 detached HEAD 时为 `commit_push`，detached 时为 `commit`，干净时为 `push`）；提交时按所选操作条件执行——含提交则先 `gitClient.commit`（透传 `stageAll`），含推送则 `gitClient.push`（远程、分支、`setUpstream`），成功路径为先调用 `onSuccess`，再关闭对话框并设置 3 秒自动消失的成功 toast（通过 `createPortal` 挂到 `document.body`）。新建分支是独立子流程，调 `gitClient.createBranch` 后用返回的 `status`/`branch` 就地刷新表单状态。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L10–L20](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx#L10-L20), [jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L63–L82](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx#L63-L82), [jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L153–L180](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx#L153-L180), [jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx:L133–L145](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/code-mode/CodeCommitPushControl.tsx#L133-L145)
+
diff --git a/knowledge/repos/jiuwenswarm/components/web-frontend/feature-connectors.md b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-connectors.md
index 8b129477..fb56881d 100644
--- a/knowledge/repos/jiuwenswarm/components/web-frontend/feature-connectors.md
+++ b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-connectors.md
@@ -12,7 +12,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/AGENTS.md
 feature: "connectors"
 entry_points: ["jiuwenswarm/channels/web/frontend/src/services/connectorApi.ts", "jiuwenswarm/channels/web/frontend/src/components/ConnectorMarket/index.tsx"]
-source_globs: ["jiuwenswarm/channels/web/frontend/src/services/connectorApi.ts", "jiuwenswarm/channels/web/frontend/src/components/ConnectorMarket/index.tsx"]
+source_globs: ["jiuwenswarm/channels/web/frontend/src/services/connectorApi.ts", "jiuwenswarm/channels/web/frontend/src/components/ConnectorMarket/index.tsx", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ExtensionPickerPanel.tsx", "jiuwenswarm/server/agent_ws_server.py", "jiuwenswarm/channels/web/frontend/src/components/ConnectorMarket/CliAuthModal.tsx", "jiuwenswarm/channels/web/frontend/src/components/ConnectorMarket/ConfirmDialog.tsx", "jiuwenswarm/channels/web/frontend/src/components/ConnectorMarket/EntityAvatar.tsx", "jiuwenswarm/channels/web/frontend/src/components/ConnectorMarket/FormPageLayout.tsx", "jiuwenswarm/channels/web/frontend/src/components/ConnectorMarket/MarketCard.tsx", "jiuwenswarm/channels/web/frontend/src/components/ConnectorMarket/MarketplacePage.tsx", "jiuwenswarm/channels/web/frontend/src/components/ConnectorMarket/PickerModal.tsx", "jiuwenswarm/server/runtime/extension_package_manager.py", "jiuwenswarm/channels/web/frontend/src/components/ConnectorMarket/Toast.tsx", "jiuwenswarm/channels/web/frontend/src/components/ConnectorMarket/ConnectTokenModal.tsx", "jiuwenswarm/channels/web/frontend/src/components/ConnectorMarket/RegisterMcpPage.tsx", "jiuwenswarm/channels/web/frontend/src/components/ConnectorMarket/mcpState.ts", "jiuwenswarm/server/runtime/mcp/registry.py", "jiuwenswarm/server/runtime/mcp/state_store.py", "jiuwenswarm/channels/web/frontend/src/components/ConnectorMarket/McpDetailPage.tsx", "jiuwenswarm/channels/web/frontend/src/types/connector.ts", "jiuwenswarm/server/runtime/mcp/marketplace.py", "jiuwenswarm/server/runtime/mcp/paths.py", "jiuwenswarm/server/runtime/mcp/skill_installer.py", "jiuwenswarm/channels/web/frontend/src/components/ConnectorMarket/MyMarketCard.tsx", "jiuwenswarm/channels/web/frontend/src/components/ConnectorMarket/usePendingConnectorFlow.tsx", "jiuwenswarm/channels/web/frontend/src/components/AgentManagementPanel/index.tsx", "jiuwenswarm/channels/web/frontend/src/components/ConnectorMarket/PluginDetailPage.tsx", "jiuwenswarm/channels/web/frontend/src/components/ConnectorMarket/UploadFileCreateModal.tsx", "jiuwenswarm/channels/web/frontend/src/components/ConnectorMarket/CreatePluginPage.tsx", "jiuwenswarm/channels/web/frontend/src/stores/connectorStore.ts"]
 ---
 
 # 连接器市场与 MCP 授权流程的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/web-frontend/feature-context-usage-indicator.md b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-context-usage-indicator.md
new file mode 100644
index 00000000..5e9c0273
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-context-usage-indicator.md
@@ -0,0 +1,54 @@
+---
+title: "上下文占用指示器（ContextUsageIndicator：环形触发器/悬浮提示/明细弹层）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx:L152-L165, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx:L121-L140, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx:L273-L304, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx:L62-L77, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx:L142-L157, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/server/runtime/agent_adapter/interface_deep.py:L18649-L18701, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx:L19-L22, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx:L144-L164, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx:L233-L238, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx:L182-L201, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx:L218-L265, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/server/runtime/agent_adapter/interface_deep.py:L18666-L18701, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx:L142-L151]
+feature: "context-usage-indicator"
+entry_points: ["jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.css", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx"]
+source_globs: ["jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.css", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx", "jiuwenswarm/server/runtime/agent_adapter/interface_deep.py", "jiuwenswarm/server/utils/stream_utils.py"]
+---
+
+# 上下文占用指示器（ContextUsageIndicator：环形触发器/悬浮提示/明细弹层）
+
+<!-- kb:knowledge owner=feature-context-usage-indicator facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的交互与展示行为**
+
+触发按钮显示 12px SVG 环形进度（`getContextRingPercent` 换算 occupancy_rate，null 时不画值弧）；hover 或键盘聚焦显示悬浮提示（占用率/已用/上限，可选 KV cache 命中率行）；点击打开明细弹层，含汇总指标、按类别的分段条形 breakdown 与类别 token 列表，类别顺序为已知 key 优先、未知类别追加并以原 category 名与次级色显示。明细支持 Escape 关闭并还原焦点、外点关闭，切换会话或快照消失时自动关闭（ContextUsageIndicator.tsx:76-77、98-107、121-140、152-165、203-215、273-304）。可访问性上使用 `aria-haspopup="dialog"`、`aria-expanded`、`aria-describedby`、role=tooltip/dialog 等（186-189、223-251）。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx:L152–L165](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx#L152-L165), [jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx:L121–L140](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx#L121-L140), [jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx:L273–L304](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx#L273-L304)
+
+<!-- kb:knowledge owner=feature-context-usage-indicator facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**API 与数据契约**
+
+前端入口是 React 组件 `ContextUsageIndicator()`，无 props：它从 `chatStore.activeSessionId` 和 `sessionStore.runtimes[id].contextUsageSnapshot` 读取数据，仅在 mode 为 `agent` 或 `team` 且快照存在时渲染（tsx:62-66、142）。消费的快照字段为 `context_window.occupancy_rate/input_tokens/limit_tokens`、`session_kv_cache_hit_rate` 与 `parts` 分类明细（tsx:145-157）。服务端侧 `get_context_usage_event(session_id, *, request_id)` 返回 `dict | None`：agent-core 缺少 `build_context_usage_snapshot` 或会话 context 未加载时返回 None；快照构造阶段的异常被捕获并降级为 None（interface_deep.py:18649-18701），但适配器创建/逐出与 context 查找发生在该保护之外。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx:L62–L77](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx#L62-L77), [jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx:L142–L157](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx#L142-L157), [jiuwenswarm/server/runtime/agent_adapter/interface_deep.py:L18649–L18701](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/server/runtime/agent_adapter/interface_deep.py#L18649-L18701)
+
+<!-- kb:knowledge owner=feature-context-usage-indicator facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**可调常量与降级显示**
+
+组件内没有外部配置项，弹层几何由模块常量控制：`VIEWPORT_GAP=8`、`TOOLTIP_GAP=5`、`TOOLTIP_ALIGN_OFFSET=3`、`DETAIL_GAP=7`（tsx:19-22）。显示降级分两类：occupancy_rate、input_tokens、limit_tokens 为 null 时显示 `chat.contextUsage.notReported` 文案（tsx:147-150）；KV cache 命中率为 null 时不显示对应行——tooltip 与明细中的该行仅在 `displayCacheRate !== null` 时渲染（tsx:151、233-238、306-311）。未知类别（无 category 定义）以原始 category 名作为标签、使用 `var(--color-text-secondary)` 颜色追加在已知类别之后（tsx:157-164）。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx:L19–L22](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx#L19-L22), [jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx:L144–L164](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx#L144-L164), [jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx:L233–L238](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx#L233-L238)
+
+<!-- kb:knowledge owner=feature-context-usage-indicator facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证：data-testid 挂点与组件级可测状态**
+
+该组件为 UI 测试提供了四个稳定的 `data-testid` 挂点：`chat-panel-context-usage-trigger`（触发按钮）、`chat-panel-context-usage-tooltip`（悬浮提示）、`chat-panel-context-usage-detail`（明细弹层）与 `chat-panel-context-usage-close`（关闭按钮），配合受控的 hover/focus 状态和 `detailSessionId` 生命周期（Escape 关闭并还原焦点、外点关闭、切换会话或快照消失时重置）可作为组件测试的断言入口。在本次展示的输入中未包含直接针对 ContextUsageIndicator 的测试文件；展示的 Python 测试（如 test_subagent_runtime_integration.py、test_task_rail.py）覆盖的是同一 JiuWenSwarmDeepAdapter 的其他职责。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx:L182–L201](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx#L182-L201), [jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx:L218–L265](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx#L218-L265)
+
+<!-- kb:knowledge owner=feature-context-usage-indicator facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**容错降级与兼容性取舍**
+
+服务端将快照构造视为尽力而为：agent-core 缺少 `build_context_usage_snapshot`（滚动升级兼容）或会话 context 未加载时返回 None；快照构造抛出的异常被捕获降级为 None，注释明确 usage 遥测不得导致 /compact 失败（interface_deep.py:18674-18701）。前端对缺失字段做显示降级：occupancy_rate/input_tokens/limit_tokens 为 null 时显示 notReported 文案，KV cache 命中率为 null 时省略对应行（ContextUsageIndicator.tsx:142-151, 233-238, 306-311）。
+
+Sources / 来源：[jiuwenswarm/server/runtime/agent_adapter/interface_deep.py:L18666–L18701](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/server/runtime/agent_adapter/interface_deep.py#L18666-L18701), [jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx:L142–L151](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx#L142-L151), [jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx:L233–L238](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ContextUsageIndicator.tsx#L233-L238)
+
diff --git a/knowledge/repos/jiuwenswarm/components/web-frontend/feature-dev-ws-traffic-logger.md b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-dev-ws-traffic-logger.md
new file mode 100644
index 00000000..108f47ca
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-dev-ws-traffic-logger.md
@@ -0,0 +1,68 @@
+---
+title: "Vite Dev WS Traffic Logger (/__dev/ws-log)"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/vite.config.ts:L350-L363, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/vite.config.ts:L423-L429, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/components/LogsPanel/index.tsx:L161-L215, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/vite.config.ts:L363-L407, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/vite.config.ts:L409-L433, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/vite.config.ts:L354-L367, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/components/LogsPanel/index.tsx:L85-L127, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/components/LogsPanel/index.tsx:L41-L76, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/components/LogsPanel/index.tsx:L134-L149, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/app_web.py:L467-L490, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/vite.config.ts:L355-L367, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/components/LogsPanel/index.tsx:L65-L76, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/app_web.py:L451-L465]
+feature: "dev-ws-traffic-logger"
+entry_points: ["jiuwenswarm/channels/web/frontend/vite.config.ts"]
+source_globs: ["jiuwenswarm/channels/web/frontend/vite.config.ts", "jiuwenswarm/channels/web/frontend/src/components/LogsPanel/index.tsx", "jiuwenswarm/channels/web/app_web.py"]
+---
+
+# Vite Dev WS Traffic Logger (/__dev/ws-log)
+
+<!-- kb:knowledge owner=feature-dev-ws-traffic-logger facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**职责与数据流**
+
+Inference / 设计推断（非作者历史意图）：
+
+插件 `devWsTrafficLogger()` 在 `configureServer` 中定位 `agent/.logs/ws-dev.log`，启动时 mkdir + 清空日志（注释说明是为避免历史数据干扰排查），随后作为 Vite 中间件接收前端上报的 /ws req/res/event 报文。写入前调用 `maskSensitive` 递归脱敏，注释指出算法与后端 SensitiveDataFilter 一致，避免 api_key/token 明文落盘并便于跨端关联。展示的代码未包含前端上报端（fetch POST 调用方），数据流中“前端→vite”一侧为推断。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/vite.config.ts:L350–L363](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/vite.config.ts#L350-L363), [jiuwenswarm/channels/web/frontend/vite.config.ts:L423–L429](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/vite.config.ts#L423-L429)
+
+<!-- kb:knowledge owner=feature-dev-ws-traffic-logger facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证入口**
+
+Inference / 设计推断（非作者历史意图）：
+
+展示范围内未见针对该插件或 `/__dev/ws-log` 的测试文件。LogsPanel 组件带有稳定的 `data-testid`（logs-panel、logs-panel-debug-toggle、logs-panel-auto-refresh-toggle、logs-panel-content 等），并区分 wsDisableCompress 开/关时的计数文案（countVisible vs countVisibleTotal），可作为 UI 层测试锚点；这些 testid 是否被实际测试使用，需查仓库测试目录确认。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/src/components/LogsPanel/index.tsx:L161–L215](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/components/LogsPanel/index.tsx#L161-L215)
+
+<!-- kb:knowledge owner=feature-dev-ws-traffic-logger facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**接口契约：GET 查询与 POST 追加**
+
+Vite 插件 `devWsTrafficLogger()` 在 `configureServer` 中向 dev server 注册 `/__dev/ws-log` 中间件。GET 返回 `{ok, entries, count}`：读取整个日志文件后按行 split、逐行 trim、过滤空行、取末尾 limit 条，每行尝试 JSON.parse，失败则原样返回该行字符串；文件不存在（ENOENT）时返回 200 与空 entries，其他读错误返回 500 `{ok:false, error:'read_failed'}`。POST 累积请求体后 JSON.parse（失败则保留原文），先经 `maskSensitive` 递归脱敏，再以 `{ts, payload}` 的 JSONL 行 append 到日志；非 GET/POST 返回 405 `{ok:false, error:'method_not_allowed'}`。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/vite.config.ts:L363–L407](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/vite.config.ts#L363-L407), [jiuwenswarm/channels/web/frontend/vite.config.ts:L409–L433](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/vite.config.ts#L409-L433)
+
+<!-- kb:knowledge owner=feature-dev-ws-traffic-logger facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**可调项：limit 参数与日志路径**
+
+日志路径由代码从项目根推导：`agent/.logs/ws-dev.log`，目录在 dev server 启动时递归创建并清空日志文件（注释说明是为避免历史数据干扰排查）。GET 支持 `limit` 查询参数，默认 300，非有限值回退 300，有效值被夹在 1–2000 之间。另有关联的调试开关：LogsPanel 通过 `/file-api/ws-debug-config` 读写 `wsDisableCompress` 布尔值，成功后派发 `jiuwenclaw:ws-reconnect-request` 自定义事件。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/vite.config.ts:L354–L367](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/vite.config.ts#L354-L367), [jiuwenswarm/channels/web/frontend/src/components/LogsPanel/index.tsx:L85–L127](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/components/LogsPanel/index.tsx#L85-L127)
+
+<!-- kb:knowledge owner=feature-dev-ws-traffic-logger facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的行为：落盘、脱敏与面板展示**
+
+插件在写盘前调用 `maskSensitive` 对 payload 递归脱敏，注释指出这是为了应对前端上报 config.get/config.validate_model 等含 api_key/token/secret 的报文，并称算法与后端 SensitiveDataFilter 一致（该一致性为注释声明，实现未在展示范围内）。前端 LogsPanel 不走 `/__dev/ws-log` 的 GET，而是通过 `/file-api/file-content?path=agent/.logs/ws-dev.log` 读取原始 JSONL，本地解析末尾 300 条，autoRefresh 开启时每 3 秒轮询；当 wsDisableCompress 关闭时过滤调试条目（含 `[ws][`、`/__dev/ws-log` 字样，或形如 ts+payload 对象的记录）。后端 app_web.py 另有 `_log_ws_business_message` 将 req/res 报文格式化为带截断的 `[ws][方向][类型]` 日志行。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/vite.config.ts:L423–L429](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/vite.config.ts#L423-L429), [jiuwenswarm/channels/web/frontend/src/components/LogsPanel/index.tsx:L41–L76](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/components/LogsPanel/index.tsx#L41-L76), [jiuwenswarm/channels/web/frontend/src/components/LogsPanel/index.tsx:L134–L149](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/components/LogsPanel/index.tsx#L134-L149), [jiuwenswarm/channels/web/app_web.py:L467–L490](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/app_web.py#L467-L490)
+
+<!-- kb:knowledge owner=feature-dev-ws-traffic-logger facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**设计取舍：文件即缓冲与脱敏前置**
+
+Inference / 设计推断（非作者历史意图）：
+
+插件选择把报文以 JSONL 追加到固定路径 `agent/.logs/ws-dev.log`，而不是内存环形缓冲：好处是 LogsPanel 可以绕开 `/__dev/ws-log` 的 GET，直接通过 `/file-api/file-content` 读原始文件，且文件天然跨请求持久；代价是每次 GET 要整读文件再切片，且 dev server 每次启动会清空日志（注释说明为避免历史数据干扰排查），重启即丢历史。写入前调用 `maskSensitive` 递归脱敏，注释指出意图是防止 config.get 等报文中的 api_key/token 明文落盘，并称算法与后端 SensitiveDataFilter 一致——该一致性及 `maskSensitive` 的具体实现（是否含类似后端 `_truncate_for_ws_log` 的长度截断）在展示范围内不可见，仅为注释声明。作为对比，后端 `_log_ws_business_message` 路径对字段有明确的字符数截断处理。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/vite.config.ts:L355–L367](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/vite.config.ts#L355-L367), [jiuwenswarm/channels/web/frontend/vite.config.ts:L423–L429](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/vite.config.ts#L423-L429), [jiuwenswarm/channels/web/frontend/src/components/LogsPanel/index.tsx:L65–L76](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/components/LogsPanel/index.tsx#L65-L76), [jiuwenswarm/channels/web/app_web.py:L451–L465](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/app_web.py#L451-L465)
+
diff --git a/knowledge/repos/jiuwenswarm/components/web-frontend/feature-frontend-incremental-lint-gate.md b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-frontend-incremental-lint-gate.md
new file mode 100644
index 00000000..e64d4426
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-frontend-incremental-lint-gate.md
@@ -0,0 +1,64 @@
+---
+title: "前端增量 ESLint 门禁（lint-changed.mjs）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs:L16-L21, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs:L28-L48, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs:L49-L61, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs:L11-L14, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs:L36-L45, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs:L18-L21, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs:L34-L61, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs:L7-L8, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs:L26-L26, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs:L9-L15, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs:L22-L26, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs:L11-L15, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs:L22-L22, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs:L75-L81]
+feature: "frontend-incremental-lint-gate"
+entry_points: ["jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs"]
+source_globs: ["jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs"]
+---
+
+# 前端增量 ESLint 门禁（lint-changed.mjs）
+
+<!-- kb:knowledge owner=feature-frontend-incremental-lint-gate facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**数据与控制流**
+
+脚本固定以前端目录为 cwd（脚本父目录，第 9 行），先取仓库根并计算前端相对前缀。变更集合 = `git diff --name-only --diff-filter=ACMR <base>` 加上 `git ls-files --others --exclude-standard`（未跟踪新文件）；由于两种 Git 命令路径基准不同，统一剥离前缀转为前端相对路径（第 29-30 行注释说明）。过滤条件：仅 `.ts/.tsx`、绝对路径仍落在 cwd 内、且不被 ESLint ignore。对每个文件读取当前内容，用 `git show base:<path>` 取基线版本，分别 `lintText` 后按诊断键（ruleId+severity+message 的 JSON 元组）做多重集相减：基线中每出现一次即抵消一条当前同类诊断，剩余的视为新增。非预期 Git 错误（非"基线中不存在该路径"）直接抛出，避免削弱检查。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs:L16–L21](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs#L16-L21), [jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs:L28–L48](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs#L28-L48), [jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs:L49–L61](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs#L49-L61)
+
+<!-- kb:knowledge owner=feature-frontend-incremental-lint-gate facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**验证入口**
+
+所提供的证据范围内没有该脚本的测试或 CI 调用；脚本自身带有运行时防御可作为部分行为验证点：参数校验抛 Usage 错误（第 12-14 行）、`git show` 失败时按 stderr 文案区分"基线无此文件"与真实 Git 错误（第 39-45 行）。摘要行输出了 checked/introduced/existing 计数，便于人工核对一次运行的行为。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs:L11–L14](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs#L11-L14), [jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs:L36–L45](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs#L36-L45)
+
+<!-- kb:knowledge owner=feature-frontend-incremental-lint-gate facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的行为**
+
+变更文件集合来自 `git diff --name-only --diff-filter=ACMR <base>` 加上 `git ls-files --others --exclude-standard`（未跟踪文件），因此新文件也纳入检查；仅处理 `.ts/.tsx`、路径仍落在前端目录内且未被 ESLint ignore 的文件。对每个文件分别 lint 基线内容（`git show base:<path>`）与当前内容，按诊断键做多重集相减，只保留新增诊断；基线中不存在该文件时 previous 为空字符串，随后仍执行同样的 lint 与抵消流程。任何新增 error 或 warning 都导致失败，既有诊断只计数不阻断。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs:L18–L21](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs#L18-L21), [jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs:L34–L61](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs#L34-L61), [jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs:L7–L8](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs#L7-L8)
+
+<!-- kb:knowledge owner=feature-frontend-incremental-lint-gate facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**设计取舍**
+
+Inference / 设计推断（非作者历史意图）：
+
+可见的取舍：以 ruleId+severity+message 为抵消键、不比较位置，使诊断在文件内移动仍可被基线抵消，但同一文件中同文案诊断数量增加时只能按条数抵消；同时该门禁对新增 warning 也失败（注释明确说明既有诊断仍可通过 `npm run lint` 查看），比仅拦 error 的做法更严格。基线获取失败时按 stderr 文案区分"基线无此文件"与其它 Git 错误，后者直接抛出而非削弱检查——这是保守处理，但依赖 Git 错误文案的字符串匹配。上述意图性判断（如与常见门禁的比较）为推断，未见于文档。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs:L26–L26](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs#L26-L26), [jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs:L36–L45](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs#L36-L45), [jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs:L7–L8](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs#L7-L8)
+
+<!-- kb:knowledge owner=feature-frontend-incremental-lint-gate facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**可配置项与固定行为设置**
+
+唯一可配置项是 CLI 参数 `--base <commit>`（缺省 `HEAD`），决定与哪个基线版本比较。其余设置为脚本内固定值：`ESLint` 实例以前端目录（脚本父目录）为 `cwd`，并开启 `reportUnusedDisableDirectives: 'error'`，即未生效的禁用注释按 error 报告；具体 lint 规则集由该实例解析，本次证据未展示配置文件本身。诊断抵消键固定为 `[ruleId, severity, message]` 的 JSON 元组（第 26 行），既非可配置项，也不含位置信息。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs:L9–L15](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs#L9-L15), [jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs:L22–L26](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs#L22-L26)
+
+<!-- kb:knowledge owner=feature-frontend-incremental-lint-gate facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**调用契约与退出行为**
+
+入口为 Node 脚本，通过 `npm run lint:changed -- [--base <commit>]` 调用。唯一参数是 `--base <commit>`（缺省 `HEAD`），参数形式不符时抛出 Usage 错误并终止（第 12-14 行）；基线 commit 由 `git rev-parse --verify` 解析，无效引用会使 Git 命令抛错。脚本复用 ESLint Node API（`new ESLint(...)`、`lintText`、`isPathIgnored`、`loadFormatter('stylish')`）对基线与当前内容分别执行 lint，只保留新增诊断。退出契约：存在新增 error 或 warning 时打印 stylish 格式结果并将 `process.exitCode` 置 1（第 75-78 行）；随后输出 checked/新增/既有计数的摘要行（第 79-81 行），该摘要仅在脚本运行到循环之后（包括诊断失败时）打印——参数错误（第 12-13 行）或被重新抛出的 Git 失败（第 39-44 行）会在此之前终止执行，不会输出摘要。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs:L11–L15](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs#L11-L15), [jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs:L22–L22](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs#L22-L22), [jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs:L36–L45](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs#L36-L45), [jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs:L75–L81](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/scripts/lint-changed.mjs#L75-L81)
+
diff --git a/knowledge/repos/jiuwenswarm/components/web-frontend/feature-goal-mode.md b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-goal-mode.md
index 54f0dbb0..8860ee47 100644
--- a/knowledge/repos/jiuwenswarm/components/web-frontend/feature-goal-mode.md
+++ b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-goal-mode.md
@@ -14,7 +14,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/AGENTS.md
 feature: "goal-mode"
 entry_points: ["jiuwenswarm/channels/web/frontend/src/features/goalMode/goalModeGate.ts", "jiuwenswarm/channels/web/frontend/src/stores/goalStore.ts", "jiuwenswarm/channels/web/frontend/src/services/webClient.ts", "jiuwenswarm/channels/web/frontend/src/hooks/useWebSocket.ts"]
-source_globs: ["jiuwenswarm/channels/web/frontend/src/features/goalMode/goalModeGate.ts", "jiuwenswarm/channels/web/frontend/src/stores/goalStore.ts", "jiuwenswarm/channels/web/frontend/src/services/webClient.ts", "jiuwenswarm/channels/web/frontend/src/hooks/useWebSocket.ts"]
+source_globs: ["jiuwenswarm/channels/web/frontend/src/features/goalMode/goalModeGate.ts", "jiuwenswarm/channels/web/frontend/src/stores/goalStore.ts", "jiuwenswarm/channels/web/frontend/src/services/webClient.ts", "jiuwenswarm/channels/web/frontend/src/hooks/useWebSocket.ts", "jiuwenswarm/server/runtime/agent_adapter/interface_deep.py", "jiuwenswarm/channels/web/frontend/src/components/GoalBar/GoalBar.css", "jiuwenswarm/channels/web/frontend/src/components/GoalBar/index.tsx", "jiuwenswarm/server/runtime/agent_adapter/interface.py", "jiuwenswarm/channels/web/frontend/src/components/GoalBar/GoalCompletedCard.tsx", "jiuwenswarm/channels/web/frontend/src/components/GoalBar/goalCompletedMessage.ts", "jiuwenswarm/channels/web/frontend/src/components/GoalBar/EditGoalModal.tsx", "jiuwenswarm/channels/web/frontend/src/components/GoalBar/OverwriteGoalConfirmModal.tsx", "jiuwenswarm/channels/web/frontend/src/types/goal.ts", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/slashCommands/registry.ts", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/slashCommands/semantics.ts", "jiuwenswarm/channels/web/frontend/src/App.tsx", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/InputArea.tsx", "jiuwenswarm/channels/web/frontend/src/features/goalPendingObjectiveBubble.ts", "jiuwenswarm/channels/web/frontend/src/stores/chatStore.ts"]
 ---
 
 # 持续目标与会话控制的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/web-frontend/feature-plan-mode.md b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-plan-mode.md
index 693c7c09..d3db218b 100644
--- a/knowledge/repos/jiuwenswarm/components/web-frontend/feature-plan-mode.md
+++ b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-plan-mode.md
@@ -12,7 +12,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/Harness.md
 feature: "plan-mode"
 entry_points: ["jiuwenswarm/channels/web/frontend/src/features/planMode/planModeGate.ts", "jiuwenswarm/channels/web/frontend/src/stores/planStore.ts"]
-source_globs: ["jiuwenswarm/channels/web/frontend/src/features/planMode/planModeGate.ts", "jiuwenswarm/channels/web/frontend/src/stores/planStore.ts"]
+source_globs: ["jiuwenswarm/channels/web/frontend/src/features/planMode/planModeGate.ts", "jiuwenswarm/channels/web/frontend/src/stores/planStore.ts", "jiuwenswarm/agents/harness/code/prompt/plan_approval.py", "jiuwenswarm/agents/harness/code/rails/code_plan_approval_interrupt_rail.py", "jiuwenswarm/agents/harness/code/rails/code_plan_approval_rail.py", "jiuwenswarm/channels/web/frontend/src/features/planMode/planEntrySource.ts", "jiuwenswarm/runtime/plan.py", "jiuwenswarm/server/agent_ws_server.py", "jiuwenswarm/server/runtime/agent_adapter/interface.py", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/InputArea.tsx", "jiuwenswarm/channels/web/frontend/src/hooks/useWebSocket.ts", "jiuwenswarm/channels/web/frontend/src/App.tsx", "jiuwenswarm/channels/browser/frontend/src/webview/chat.html", "jiuwenswarm/agents/harness/work/rails/work_agent_mode_rail.py"]
 ---
 
 # 计划模式与多入口切换限制的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/web-frontend/feature-rsi-experiment-ui.md b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-rsi-experiment-ui.md
new file mode 100644
index 00000000..5f54e67b
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-rsi-experiment-ui.md
@@ -0,0 +1,30 @@
+---
+title: "RSI 自我改进实验页（创建/列表/配置回显）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/rsi/components/CreateExperimentDialog.tsx:L247-L316, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/rsi/artifact_adapter.py:L370-L398, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/agents/harness/common/rsi/artifact_adapter.py:L400-L434, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/rsi/featureConfig.ts:L3-L33, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/rsi/components/CreateExperimentDialog.tsx:L89-L103, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/rsi/components/ConfigInfoDialog.tsx:L28-L65]
+feature: "rsi-experiment-ui"
+entry_points: ["jiuwenswarm/channels/web/frontend/src/features/rsi/RsiPage.tsx", "jiuwenswarm/channels/web/frontend/src/features/rsi/components/ConfigInfoDialog.tsx", "jiuwenswarm/channels/web/frontend/src/features/rsi/components/CreateExperimentDialog.tsx"]
+source_globs: ["jiuwenswarm/channels/web/frontend/src/features/rsi/RsiPage.tsx", "jiuwenswarm/channels/web/frontend/src/features/rsi/components/ConfigInfoDialog.tsx", "jiuwenswarm/channels/web/frontend/src/features/rsi/components/CreateExperimentDialog.tsx", "jiuwenswarm/agents/harness/common/rsi/artifact_adapter.py", "jiuwenswarm/channels/web/frontend/src/features/rsi/components/RsiDetail.tsx", "jiuwenswarm/channels/web/frontend/src/features/rsi/components/RsiRail.tsx", "jiuwenswarm/channels/web/frontend/src/features/rsi/rsiStore.ts", "jiuwenswarm/channels/web/frontend/src/features/rsi/featureConfig.ts", "jiuwenswarm/channels/web/frontend/src/features/rsi/types.ts", "jiuwenswarm/channels/web/frontend/src/features/rsi/styles/rsi.css", "jiuwenswarm/channels/web/frontend/src/features/rsi/components/RsiIntroduction.tsx", "jiuwenswarm/channels/web/frontend/src/features/rsi/mockData.ts", "jiuwenswarm/channels/web/frontend/src/features/rsi/rsiPresentation.ts", "jiuwenswarm/channels/web/frontend/src/features/rsi/components/RsiSelectedInfo.tsx", "jiuwenswarm/agents/harness/common/rsi/paper_provider.py", "jiuwenswarm/agents/harness/common/rsi/projector.py", "jiuwenswarm/channels/web/frontend/src/features/rsi/useRsiEvents.ts"]
+---
+
+# RSI 自我改进实验页（创建/列表/配置回显）
+
+<!-- kb:knowledge owner=feature-rsi-experiment-ui facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**前后端契约：task.create / dataset.validate 与 Provider 适配接口**
+
+前端创建实验走 rsiTaskCreate → rsiTrainingStart（启动）→ rsiTaskList（回查快照）的链路：字段按契约 §6.1 task.create 组装，HARNESS 分支带 input_file/model_refs.optimizer+tester/max_iterations/evaluation_method（'agent' 映射为 llm_as_judge），ARTIFACT 分支按 artifact_type 附加 optimization_instruction/artifact_path/web_proxy；启动或列表回查失败均被吞掉，不阻断创建反馈。后端 ArtifactEngineAdapter 暴露 run/resume/pause/terminate/read_state/read_report/get_tree/locate_artifact 作为 Provider 的公共入口，validate_input 将 Provider 结果归一为 RsiDatasetResult(valid, sample_count, errors)。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/src/features/rsi/components/CreateExperimentDialog.tsx:L247–L316](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/rsi/components/CreateExperimentDialog.tsx#L247-L316), [jiuwenswarm/agents/harness/common/rsi/artifact_adapter.py:L370–L398](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/rsi/artifact_adapter.py#L370-L398), [jiuwenswarm/agents/harness/common/rsi/artifact_adapter.py:L400–L434](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/agents/harness/common/rsi/artifact_adapter.py#L400-L434)
+
+<!-- kb:knowledge owner=feature-rsi-experiment-ui facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**配置项：特性开关、表单默认值与配置回显**
+
+RSI 特性开关 featureConfig.ts 默认启用（rsiFeatureEnabled = true），normalizeRSIEnabled 把非布尔值按字符串归一，仅 '0'/'false'/'no'/'off' 视为关闭，并通过 useSyncExternalStore 提供响应式读取。创建表单的默认值：scenario='HARNESS'、artifactType='PAPER'、evaluationMethod='agent'、maxIterations=2（切到 PROGRAM 时重置为 3 但不展示该字段），package_id 固定空串 DEFAULT_RSI_PACKAGE_ID；配置回显由 ConfigInfoDialog 只读展示 task.config 快照（模型、数据集、optimization_instruction、web_proxy 是否配置、artifact_path、max_iterations，按分支条件显示）。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/src/features/rsi/featureConfig.ts:L3–L33](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/rsi/featureConfig.ts#L3-L33), [jiuwenswarm/channels/web/frontend/src/features/rsi/components/CreateExperimentDialog.tsx:L89–L103](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/rsi/components/CreateExperimentDialog.tsx#L89-L103), [jiuwenswarm/channels/web/frontend/src/features/rsi/components/ConfigInfoDialog.tsx:L28–L65](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/rsi/components/ConfigInfoDialog.tsx#L28-L65)
+
diff --git a/knowledge/repos/jiuwenswarm/components/web-frontend/feature-share-image-export.md b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-share-image-export.md
new file mode 100644
index 00000000..3deab635
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-share-image-export.md
@@ -0,0 +1,38 @@
+---
+title: "会话分享图导出：任务注册表与无头渲染器"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/share_image_export.py:L69-L98, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/share_image_export.py:L29-L40, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/vite.config.ts:L626-L636, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/vite.config.ts:L585-L597, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/vite.config.ts:L625-L628, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/vite.config.ts:L733-L736, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/vite.config.ts:L746-L765, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/vite.config.ts:L626-L673, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/vite.config.ts:L679-L731, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/share_image_export.py:L250-L271, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/shareImageExport.tsx:L1466-L1500]
+feature: "share-image-export"
+entry_points: ["jiuwenswarm/channels/web/frontend/vite.config.ts", "jiuwenswarm/channels/web/share_image_export.py"]
+source_globs: ["jiuwenswarm/channels/web/frontend/vite.config.ts", "jiuwenswarm/channels/web/share_image_export.py", "jiuwenswarm/channels/web/frontend/src/features/shareImageExport.tsx", "jiuwenswarm/channels/web/frontend/src/features/shareImageArchive.ts", "jiuwenswarm/channels/web/frontend/src/features/shareImageExport.css", "jiuwenswarm/channels/web/app_web.py", "jiuwenswarm/channels/web/frontend/src/features/shareImageJob.ts", "jiuwenswarm/channels/web/frontend/src/features/shareImagePng.worker.ts", "jiuwenswarm/channels/web/frontend/src/features/shareImagePngEncoder.ts", "jiuwenswarm/channels/web/frontend/src/App.tsx", "jiuwenswarm/channels/web/frontend/src/main.tsx", "jiuwenswarm/channels/web/frontend/src/features/shareImageRaster.ts"]
+---
+
+# 会话分享图导出：任务注册表与无头渲染器
+
+<!-- kb:knowledge owner=feature-share-image-export facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**浏览器选择、locale 与超时参数**
+
+渲染浏览器由 jiuwenswarm 配置的 browser 段决定：chrome_path 可为字符串，或按平台（windows/macos/linux/default）取值的字典；配置了路径但文件不存在会抛 configured_share_export_browser_not_found。browser_type 为 msedge/edge 等别名时使用 Edge channel，否则 chrome；未配置路径时通过 channel 启动。locale 由 POST 请求体传入，缺省 'zh'，Runner 会据此 i18n.changeLanguage。时间常量硬编码在渲染器：任务 TTL 1 小时（开发态同为 60*60*1000ms），渲染 init 超时 15s、idle 与绝对超时各 15 分钟、轮询 0.25s，PNG 输出宽度固定 2250、最大高度 128000。
+
+Sources / 来源：[jiuwenswarm/channels/web/share_image_export.py:L69–L98](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/share_image_export.py#L69-L98), [jiuwenswarm/channels/web/share_image_export.py:L29–L40](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/share_image_export.py#L29-L40), [jiuwenswarm/channels/web/frontend/vite.config.ts:L626–L636](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/vite.config.ts#L626-L636)
+
+<!-- kb:knowledge owner=feature-share-image-export facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**任务 API 的状态码与状态契约**
+
+POST /share-api/jobs 创建新任务时返回 202；若同一 session 已有 queued/running 任务则不重复创建，返回 200 且带 reused:true。GET /share-api/jobs?session_id= 只返回活动任务，找不到时 404 active_job_not_found，缺 session_id 时 400。任务状态统一为 {job_id, session_id, filename, state(queued|running|completed|failed), phase, error}；GET /share-api/jobs/:jobId/download 仅在 completed 状态可用，否则 409 job_not_completed。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/vite.config.ts:L585–L597](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/vite.config.ts#L585-L597), [jiuwenswarm/channels/web/frontend/vite.config.ts:L625–L628](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/vite.config.ts#L625-L628), [jiuwenswarm/channels/web/frontend/vite.config.ts:L733–L736](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/vite.config.ts#L733-L736), [jiuwenswarm/channels/web/frontend/vite.config.ts:L746–L765](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/vite.config.ts#L746-L765)
+
+<!-- kb:knowledge owner=feature-share-image-export facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**不可变快照 + 子进程无头渲染的流水线**
+
+导出分三段：dev Vite 插件先从 agent/sessions 下的 history.jsonl（或 legacy history.json）与 metadata.json 构建不可变快照，写入临时目录 snapshot.json，然后 spawn `uv run python -m jiuwenswarm.channels.web.share_image_export` 子进程，通过逐行解析子进程 stdout 的 NDJSON 事件（phase/error/filename）更新内存中 Map 里的任务状态；Python 渲染器再用 Playwright 启动独立 headless Chromium 打开 `/share-export-runner?job_id=`，前端 Runner fetch 快照渲染，并通过反复替换（而非原地修改）`window.__SHARE_IMAGE_EXPORT_STATE` 对象暴露状态供轮询。任务判定完成需同时满足退出码 0、无 job.error 且 resultPath 文件存在。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/vite.config.ts:L626–L673](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/vite.config.ts#L626-L673), [jiuwenswarm/channels/web/frontend/vite.config.ts:L679–L731](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/vite.config.ts#L679-L731), [jiuwenswarm/channels/web/share_image_export.py:L250–L271](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/share_image_export.py#L250-L271), [jiuwenswarm/channels/web/frontend/src/features/shareImageExport.tsx:L1466–L1500](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/shareImageExport.tsx#L1466-L1500)
+
diff --git a/knowledge/repos/jiuwenswarm/components/web-frontend/feature-speech-interaction.md b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-speech-interaction.md
index 8e338163..e39bbf05 100644
--- a/knowledge/repos/jiuwenswarm/components/web-frontend/feature-speech-interaction.md
+++ b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-speech-interaction.md
@@ -13,7 +13,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/README.md
 feature: "speech-interaction"
 entry_points: ["jiuwenswarm/channels/web/frontend/src/features/taskAsr/useTaskAsr.ts", "jiuwenswarm/channels/web/frontend/src/features/taskAsr/featureFlag.ts", "jiuwenswarm/channels/web/frontend/src/utils/tts.ts", "jiuwenswarm/channels/web/frontend/src/hooks/useSpeech.ts"]
-source_globs: ["jiuwenswarm/channels/web/frontend/src/features/taskAsr/useTaskAsr.ts", "jiuwenswarm/channels/web/frontend/src/features/taskAsr/featureFlag.ts", "jiuwenswarm/channels/web/frontend/src/utils/tts.ts", "jiuwenswarm/channels/web/frontend/src/hooks/useSpeech.ts"]
+source_globs: ["jiuwenswarm/channels/web/frontend/src/features/taskAsr/useTaskAsr.ts", "jiuwenswarm/channels/web/frontend/src/features/taskAsr/featureFlag.ts", "jiuwenswarm/channels/web/frontend/src/utils/tts.ts", "jiuwenswarm/channels/web/frontend/src/hooks/useSpeech.ts", "jiuwenswarm/channels/web/frontend/src/hooks/useWebSocket.ts", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/InputArea.tsx", "jiuwenswarm/channels/web/frontend/src/utils/speechDetection/silero.worker.ts", "jiuwenswarm/channels/web/frontend/src/utils/speechDetection/sileroVad.ts", "jiuwenswarm/channels/web/frontend/src/utils/speechDetection/speechGate.ts"]
 ---
 
 # 语音输入、回复朗读与停止的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/web-frontend/feature-web-asset-publish-flow.md b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-web-asset-publish-flow.md
new file mode 100644
index 00000000..fce3dbb7
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-web-asset-publish-flow.md
@@ -0,0 +1,54 @@
+---
+title: "Web 资产发布流程（prepare/commit/轮询/提交锁）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts:L87-L114, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts:L151-L173, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts:L238-L249, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts:L257-L285, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/types/assetPublish.ts:L1-L3, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/assetPublishState.ts:L7-L15, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/assetPublishEvents.ts:L1-L4, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/assetPublication.ts:L17-L20, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts:L145-L173, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts:L96-L114, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts:L67-L70, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/assetPublishState.ts:L23-L41, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/features/assetPublishState.ts:L47-L60, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts:L20-L33, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts:L90-L95, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts:L174-L188, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts:L261-L269]
+feature: "web-asset-publish-flow"
+entry_points: ["jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts"]
+source_globs: ["jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts", "jiuwenswarm/channels/web/frontend/src/types/assetPublish.ts", "jiuwenswarm/channels/web/frontend/src/features/assetPublication.ts", "jiuwenswarm/channels/web/frontend/src/features/assetPublishErrors.ts", "jiuwenswarm/channels/web/frontend/src/features/assetPublishEvents.ts", "jiuwenswarm/channels/web/frontend/src/features/assetPublishState.ts"]
+---
+
+# Web 资产发布流程（prepare/commit/轮询/提交锁）
+
+<!-- kb:knowledge owner=feature-web-asset-publish-flow facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**useAssetPublish Hook 的对外契约**
+
+`useAssetPublish(reference, restored?)` 是发布流程的前端入口，返回 `prepare`、`commit`、`refresh`、`edit` 等操作以及 `metadata`、`draft`、`record`、`records`、`submissionLocked`、`busy`、`error`、`attempted`、`loggedIn` 等状态。远程交互覆盖五个方法：`assetPublishApi.describe`、`.records`、`.prepare`、`.commit`、`.status`。错误键来源混合：`describe/prepare/records` 失败走 `publishFailureKey` 映射（assetPublishErrors.ts 的安全键表加兜底 `requestFailed`），而轮询失败直接设 `statusFailed`（L163–164），草稿过期设 `expired`（L213–215），提交失败按 `definitiveCommitRejection` 结果设 `expired`/`commitRejected`/`commitUncertain`（L238–248）。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts:L87–L114](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts#L87-L114), [jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts:L151–L173](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts#L151-L173), [jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts:L238–L249](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts#L238-L249), [jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts:L257–L285](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts#L257-L285)
+
+<!-- kb:knowledge owner=feature-web-asset-publish-flow facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的发布行为**
+
+支持五种资产类型（skill、agent_template、agent_group、plugin、mcp，types/assetPublish.ts L1），流程含 prepare/commit/过期检查/提交锁/记录找回/状态轮询。`publishOutcome` 把 `PublishRecord` 归一为 queued/uploading/failed/pending_moderation/published/unknown（assetPublishState.ts L7–15）；'unknown' 结果会维持提交锁（L53）。`openAssetPublish` 仅派发 `asset-publish-open` 自定义事件，监听方不在本次展示范围内。发布状态展示层提供中英双语标签，详情页只显示已确认的状态（assetPublication.ts L17–20）。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/src/types/assetPublish.ts:L1–L3](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/types/assetPublish.ts#L1-L3), [jiuwenswarm/channels/web/frontend/src/features/assetPublishState.ts:L7–L15](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/assetPublishState.ts#L7-L15), [jiuwenswarm/channels/web/frontend/src/features/assetPublishEvents.ts:L1–L4](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/assetPublishEvents.ts#L1-L4), [jiuwenswarm/channels/web/frontend/src/features/assetPublication.ts:L17–L20](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/assetPublication.ts#L17-L20)
+
+<!-- kb:knowledge owner=feature-web-asset-publish-flow facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**架构：状态流、轮询与找回**
+
+useAssetPublish 以 prepare→draft→commit→record→轮询为主线：draft 确认后 commit 产生 PublishRecord，随后按 execution_status（queued/uploading）轮询 assetPublishApi.status；L156–L168 显示下一次轮询在上一次请求完成后再延迟 5 秒调度（首次延迟 2 秒），因此实际间隔包含请求耗时。异步竞态通过 generation 计数 + scope（OAuth 提供者与令牌拼接，L29）双重校验（current()，L67–L70）过滤过期响应。断线恢复是条件性的：仅当 description 尚未加载时订阅 webClient.onStateChange，在连接 ready 时触发 refresh（L145–L150）；refresh 在 records 中按 operation_id 或 draft_id 匹配活跃提交并恢复其状态（L99–L104）。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts:L145–L173](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts#L145-L173), [jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts:L96–L114](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts#L96-L114), [jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts:L67–L70](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts#L67-L70)
+
+<!-- kb:knowledge owner=feature-web-asset-publish-flow facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**取舍：幂等键与不确定失败的保守锁**
+
+commit 采用单次尝试持有一个幂等请求 ID（crypto.randomUUID()，L218–L222）：createCommitAttempt 在成功后缓存结果并复用，失败后允许用同一 ID 重试（assetPublishState.ts L23–L41），以避免重复上传。错误处理刻意保守：只有 definitiveCommitRejection 识别出的明确拒绝（draft_expired 及 invalid_draft/draft_not_found/auth_required 等正则，assetPublishState.ts L47–L60）才释放提交锁并丢弃幂等键；其余失败仅设 error 'commitUncertain' 并保留 activeSubmission（L238–L248），后续靠 refresh 按 ID 找回记录（L96–L104）。代价是不确定状态下用户停留在锁定态等待恢复。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/src/features/assetPublishState.ts:L23–L41](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/assetPublishState.ts#L23-L41), [jiuwenswarm/channels/web/frontend/src/features/assetPublishState.ts:L47–L60](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/features/assetPublishState.ts#L47-L60), [jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts:L238–L249](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts#L238-L249)
+
+<!-- kb:knowledge owner=feature-web-asset-publish-flow facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**发布元数据的默认值与修改守卫**
+
+发布元数据的前端默认值由 `emptyMetadata` 定义：version 固定为 '1.0.0'，visibility 为 'public'，asset_name 与 display_name 初始取自 `reference.local_id`；未传入恢复值 `restored` 时以该默认值初始化（useAssetPublish.ts L20–L33）。服务端返回的 `description.defaults` 仅在用户未编辑过（`edited.current` 为假）时覆盖本地默认值（L94、L138）。对 `setTargetAssetId`/`setForce`/`edit` 的每次修改都先经 `invalidate()`：当存在活跃提交（`activeSubmission`）或进行中的操作（`busyRef`）时拒绝修改并保留当前 draft/record，否则自增 generation 使过期异步响应失效并清空 draft 与 attempt（L174–L188、L261–L269）。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts:L20–L33](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts#L20-L33), [jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts:L90–L95](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts#L90-L95), [jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts:L174–L188](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts#L174-L188), [jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts:L261–L269](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/hooks/useAssetPublish.ts#L261-L269)
+
diff --git a/knowledge/repos/jiuwenswarm/components/web-frontend/feature-web-chat.md b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-web-chat.md
index 12669a83..44e48bab 100644
--- a/knowledge/repos/jiuwenswarm/components/web-frontend/feature-web-chat.md
+++ b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-web-chat.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/对话.md
 feature: "web-chat"
 entry_points: ["jiuwenswarm/channels/web/frontend/src/hooks/useWebSocket.ts"]
-source_globs: ["jiuwenswarm/channels/web/frontend/src/hooks/useWebSocket.ts", "jiuwenswarm/channels/web/frontend/src/*"]
+source_globs: ["jiuwenswarm/channels/web/frontend/src/hooks/useWebSocket.ts", "jiuwenswarm/channels/web/frontend/src/*", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/index.tsx", "jiuwenswarm/gateway/channel_manager/web/app_web_handlers.py", "jiuwenswarm/gateway/channel_manager/base.py", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/BeamSearchTree.css", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/BeamSearchTree.tsx", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ChatPanel.css", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/MediaRenderer.tsx", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/MessageItem.tsx", "jiuwenswarm/common/chat_final.py", "jiuwenswarm/channels/web/frontend/src/utils/chatFinalProtocol.ts", "jiuwenswarm/channels/web/frontend/src/utils/finalContent.ts", "jiuwenswarm/channels/web/frontend/src/types/message.ts", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/chatTimelineClock.ts", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/MessageList.tsx", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/clipboardImagePaste.ts", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/InputArea.tsx", "jiuwenswarm/channels/web/frontend/src/components/MarkdownRenderer/diagrams/DiagramViewer.tsx", "jiuwenswarm/channels/web/frontend/src/components/MarkdownRenderer/diagrams/diagramExport.ts", "jiuwenswarm/channels/web/frontend/src/components/MarkdownRenderer/diagrams/useDiagramExportActions.ts", "jiuwenswarm/channels/web/frontend/src/components/MarkdownRenderer/codeBlocks/fencedCode.ts", "jiuwenswarm/channels/web/frontend/src/components/MarkdownRenderer/codeBlocks/registry.tsx", "jiuwenswarm/channels/web/frontend/src/components/MarkdownRenderer/codeBlocks/types.ts", "jiuwenswarm/gateway/message_handler/command_parser/slash_command.py", "jiuwenswarm/gateway/message_handler/message_handler.py", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/imeComposition.ts", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/InlineQuestionCard.tsx", "jiuwenswarm/channels/web/frontend/src/components/InteractionSlot/index.tsx", "jiuwenswarm/channels/web/frontend/src/components/InteractionSlot/promptRouting.ts", "jiuwenswarm/channels/web/frontend/src/features/trajectory/primitives/markdown/katex.tsx", "jiuwenswarm/channels/web/frontend/src/components/MarkdownRenderer/index.ts", "jiuwenswarm/channels/web/frontend/src/components/MarkdownRenderer/markdownTransforms.ts", "jiuwenswarm/channels/web/frontend/src/features/trajectory/primitives/markdown/render.tsx", "jiuwenswarm/channels/web/frontend/src/components/MarkdownRenderer/MarkdownRenderer.tsx", "jiuwenswarm/channels/web/frontend/src/components/MarkdownRenderer/markdownPlugins.ts", "jiuwenswarm/channels/web/frontend/src/components/MarkdownRenderer/diagrams/MermaidDiagram.tsx", "jiuwenswarm/channels/web/frontend/src/components/MarkdownRenderer/diagrams/mermaidLayout.ts", "jiuwenswarm/channels/web/frontend/src/components/MarkdownRenderer/diagrams/mermaidRuntime.ts", "jiuwenswarm/server/runtime/agent_adapter/interface_deep.py", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/PickerPanel.tsx", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/PickerSearchInput.tsx", "jiuwenswarm/channels/web/frontend/src/components/InteractionSlot/QaSummaryCard.tsx", "jiuwenswarm/channels/web/frontend/src/components/InteractionSlot/qaSummary.ts", "jiuwenswarm/channels/web/frontend/src/components/MarkdownRenderer/math/remarkLatexDelimiters.ts", "jiuwenswarm/channels/web/frontend/src/hooks/useResponsive.ts", "jiuwenswarm/channels/web/frontend/src/utils/enabledExtensions.ts", "jiuwenswarm/channels/web/frontend/src/services/sessionEventGate.ts", "jiuwenswarm/server/agent_ws_server.py", "jiuwenswarm/channels/web/frontend/src/features/sessionOutput.ts", "jiuwenswarm/channels/web/frontend/src/features/trajectory/primitives/markdown/highlight.ts", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/SkillTreePath.tsx", "jiuwenswarm/channels/web/frontend/src/types/skillTree.ts", "jiuwenswarm/gateway/channel_manager/web/ws_connection_adapter.py", "jiuwenswarm/channels/web/frontend/src/services/streamDeltaBatcher.ts", "jiuwenswarm/channels/web/frontend/src/utils/svgDimensions.ts", "jiuwenswarm/channels/web/frontend/src/components/MarkdownRenderer/diagrams/SvgDiagram.tsx", "jiuwenswarm/channels/web/frontend/src/components/MarkdownRenderer/diagrams/svgPreview.ts", "jiuwenswarm/channels/web/frontend/src/components/MarkdownRenderer/isolatedPreview.ts", "jiuwenswarm/channels/web/frontend/src/utils/symphonyCommandDisplay.ts", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/TeamEventGroupDisplay.tsx", "jiuwenswarm/channels/web/frontend/src/components/teamArea/ExpandedPanel.tsx", "jiuwenswarm/channels/web/frontend/src/components/teamArea/ExpandedPanelTabs.tsx", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/timelineRowState.tsx", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/useProcessTreeCollapse.ts", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ToolCallDisplay.tsx", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/ToolGroupDisplay.tsx", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/unsentImageDiscard.ts", "jiuwenswarm/channels/web/frontend/src/utils/documentMessage.ts", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/VirtualTimeline.tsx", "jiuwenswarm/channels/web/frontend/src/stores/sessionStore.ts", "jiuwenswarm/gateway/channel_manager/web/web_connect.py", "jiuwenswarm/gateway/channel_manager/web/web_channel_app.py", "jiuwenswarm/channels/web/frontend/src/stores/chatStore.ts", "jiuwenswarm/channels/web/frontend/src/utils/writeClipboard.ts", "jiuwenswarm/channels/web/frontend/src/features/contextUsage/contextUsageCategories.ts", "jiuwenswarm/channels/web/frontend/src/features/contextUsage/contextUsageModel.ts", "jiuwenswarm/channels/web/frontend/tailwind.config.js", "jiuwenswarm/channels/web/app_web.py", "jiuwenswarm/channels/web/frontend/src/features/chatTimeline/buildTurnTimeline.ts", "jiuwenswarm/channels/web/frontend/src/features/trajectory/primitives/markdown/MarkdownText.tsx", "jiuwenswarm/channels/web/file_picker.py", "jiuwenswarm/channels/web/frontend/src/stores/pendingQuestionQueue.ts", "jiuwenswarm/channels/web/frontend/src/App.tsx", "jiuwenswarm/channels/web/frontend/src/features/trajectory/SingleAgentSurface.tsx", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/slashCommands/semantics.ts", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/slashCommands/registry.ts", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/teamEventUtils.ts", "jiuwenswarm/channels/web/frontend/src/features/teamLeaderMessages.ts", "jiuwenswarm/channels/web/frontend/src/features/chatTimeline/projectTimelineItems.ts", "jiuwenswarm/channels/web/frontend/src/utils/timestamp.ts", "jiuwenswarm/channels/web/frontend/src/components/ChatPanel/toolCategory.ts", "jiuwenswarm/channels/web/frontend/src/features/tool-events/toolEventNormalizer.ts", "jiuwenswarm/channels/web/frontend/src/stores/toolResultLifecycle.ts", "jiuwenswarm/channels/web/frontend/src/features/tool-events/reviewerMetadata.ts", "jiuwenswarm/channels/web/frontend/src/features/chatTimeline/index.ts", "jiuwenswarm/channels/web/frontend/src/utils/userId.ts", "jiuwenswarm/channels/web/frontend/src/features/UserQuestionModal/index.tsx", "jiuwenswarm/channels/web/frontend/src/utils/uuid.ts", "jiuwenswarm/channels/web/frontend/src/services/webClient.ts", "jiuwenswarm/channels/browser/frontend/src/webview/chat.html", "jiuwenswarm/server/runtime/gateway_adapter/workspace_file_adapter.py", "jiuwenswarm/gateway/routing/base_ws_channel.py", "jiuwenswarm/channels/web/frontend/src/utils/wsEventDedup.ts", "jiuwenswarm/channels/web/frontend/src/types/websocket.ts"]
 ---
 
 # Web 对话与流式状态 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/web-frontend/feature-web-i18n-zh-en.md b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-web-i18n-zh-en.md
new file mode 100644
index 00000000..805d0bb6
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-web-i18n-zh-en.md
@@ -0,0 +1,54 @@
+---
+title: "Web 前端中英双语 i18n 初始化（jiuwenswarm/channels/web/frontend）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/i18n/index.ts:L1-L30, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/App.tsx:L2114-L2125, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/i18n/index.ts:L15-L28, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/i18n/index.ts:L1-L18, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/App.tsx:L1878-L1898, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/i18n/index.ts:L12-L30, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/frontend/src/i18n/index.ts:L17-L27]
+feature: "web-i18n-zh-en"
+entry_points: ["jiuwenswarm/channels/web/frontend/src/i18n/index.ts"]
+source_globs: ["jiuwenswarm/channels/web/frontend/src/i18n/index.ts", "jiuwenswarm/channels/web/frontend/src/App.tsx"]
+---
+
+# Web 前端中英双语 i18n 初始化（jiuwenswarm/channels/web/frontend）
+
+<!-- kb:knowledge owner=feature-web-i18n-zh-en facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**静态资源 + 本地检测 + 后端同步的分层**
+
+前端 i18n 分两层：初始化层在模块加载时把 zh/en 两份 JSON 静态 import 进 `resources`，经 `LanguageDetector`（只查/只写 localStorage）与 `initReactI18next` 完成配置；运行层在 App 组件中，`isConnected` 变化触发的 effect 从后端 `locale.get_conf` 读取 `preferred_language` 并调用 `changeLanguage` 同步显示语言（注释说明与 config.yaml 保持一致）。因此启动初期语言由 localStorage 缓存决定，无缓存时落到 fallbackLng 'zh'；连接后可能被后端值覆盖（含 en）。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/src/i18n/index.ts:L1–L30](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/i18n/index.ts#L1-L30), [jiuwenswarm/channels/web/frontend/src/App.tsx:L2114–L2125](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/App.tsx#L2114-L2125)
+
+<!-- kb:knowledge owner=feature-web-i18n-zh-en facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**init 选项与检测顺序**
+
+`i18n.init` 的关键设置：`fallbackLng: 'zh'`、`supportedLngs: ['zh', 'en']`、`interpolation.escapeValue: false`、`detection.order` 与 `detection.caches` 均为 `['localStorage']`。源码注释说明意图：未手动选择语言时默认中文（与后端 `preferred_language` 默认值一致），不跟随 navigator，因为桌面 WebView2 常为 en-US 会导致启动初期显示英文。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/src/i18n/index.ts:L15–L28](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/i18n/index.ts#L15-L28)
+
+<!-- kb:knowledge owner=feature-web-i18n-zh-en facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的双语行为与依赖**
+
+支持中文（zh）与英文（en）两种语言，翻译文案来自静态打包的 `./locales/zh.json` 与 `./locales/en.json`，无运行时按需加载；语言选择持久化在 localStorage。组件通过 react-i18next 的 `t()` 消费翻译（如 App.tsx 的外部 CLI 文件选择标题），且后端 `preferred_language`（仅 zh/en 值时）会在连接后覆盖前端显示语言。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/src/i18n/index.ts:L1–L18](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/i18n/index.ts#L1-L18), [jiuwenswarm/channels/web/frontend/src/App.tsx:L1878–L1898](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/App.tsx#L1878-L1898), [jiuwenswarm/channels/web/frontend/src/App.tsx:L2114–L2125](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/App.tsx#L2114-L2125)
+
+<!-- kb:knowledge owner=feature-web-i18n-zh-en facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**初始化入口与运行时语言同步**
+
+`src/i18n/index.ts` 在模块加载时链式调用 `i18n.use(LanguageDetector).use(initReactI18next).init({...})` 完成配置，并默认导出该 i18n 实例供其他模块引用。运行时语言切换的公开途径是实例方法 `i18n.changeLanguage(lang)`：App 组件在 `isConnected` 变为真后通过 `webRequest('locale.get_conf')` 读取后端 `preferred_language`，仅当值为 `'zh'` 或 `'en'` 时调用 `changeLanguage`，请求失败被空的 `.catch(() => {})` 静默吞掉，不影响主流程。组件层消费翻译使用 `t()`（如 `t("config.externalCli.selectFileTitle", { agent })`）。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/src/i18n/index.ts:L12–L30](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/i18n/index.ts#L12-L30), [jiuwenswarm/channels/web/frontend/src/App.tsx:L2114–L2125](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/App.tsx#L2114-L2125), [jiuwenswarm/channels/web/frontend/src/App.tsx:L1878–L1898](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/App.tsx#L1878-L1898)
+
+<!-- kb:knowledge owner=feature-web-i18n-zh-en facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**默认中文与 localStorage-only 检测的取舍**
+
+检测顺序与缓存均只含 `localStorage`，且 `fallbackLng: 'zh'`：源码注释明确意图——未手动选择语言时默认中文（与后端 `preferred_language` 默认值一致），不跟随 navigator，因为桌面 WebView2 常为 en-US 会导致启动初期显示英文；代价是非中文浏览器用户在首次手动选择或后端同步之前先看到中文。另一取舍是后端同步的健壮性：`locale.get_conf` 返回非 zh/en 值时静默忽略、请求失败时静默吞掉，换取语言同步失败不阻塞连接后的主流程。
+
+Sources / 来源：[jiuwenswarm/channels/web/frontend/src/i18n/index.ts:L17–L27](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/i18n/index.ts#L17-L27), [jiuwenswarm/channels/web/frontend/src/App.tsx:L2114–L2125](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/src/App.tsx#L2114-L2125)
+
diff --git a/knowledge/repos/jiuwenswarm/components/web-frontend/feature-web-native-directory-picker.md b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-web-native-directory-picker.md
new file mode 100644
index 00000000..b6a129bc
--- /dev/null
+++ b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-web-native-directory-picker.md
@@ -0,0 +1,64 @@
+---
+title: "Web 通道本机目录/可执行文件选择器（directory_picker）"
+created: 2026-10-06
+updated: 2026-10-06
+type: architecture
+tags: [jiuwenswarm]
+sources: [openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/directory_picker.py:L24-L25, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/directory_picker.py:L51-L58, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/directory_picker.py:L296-L309, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/directory_picker.py:L118-L123, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/directory_picker.py:L152-L159, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/directory_picker.py:L28-L36, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/directory_picker.py:L203-L209, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/directory_picker.py:L476-L505, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/directory_picker.py:L39-L48, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/directory_picker.py:L510-L520, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/directory_picker.py:L415-L443, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/directory_picker.py:L290-L299, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/directory_picker.py:L339-L346, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/directory_picker.py:L488-L493, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/directory_picker.py:L418-L437, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/directory_picker.py:L290-L295, openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:jiuwenswarm/channels/web/directory_picker.py:L427-L443]
+feature: "web-native-directory-picker"
+entry_points: ["jiuwenswarm/channels/web/directory_picker.py"]
+source_globs: ["jiuwenswarm/channels/web/directory_picker.py"]
+---
+
+# Web 通道本机目录/可执行文件选择器（directory_picker）
+
+<!-- kb:knowledge owner=feature-web-native-directory-picker facet=configuration pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**常量与运行参数**
+
+该模块没有用户可配置项：对话框标题是模块常量 `_DIALOG_TITLE`（"选择项目目录"）与 `_FILE_DIALOG_TITLE`（"Select executable file"），仅 `select_file_native` 的 `title` 参数可覆盖。子进程超时硬编码为 600 秒（`_run_capture` 默认值与 tkinter 子进程调用均如此）。tkinter 子进程内部使用的 `JIUWEN_DIR_PICKER_INITIAL`/`JIUWEN_DIR_PICKER_TITLE`/`JIUWEN_FILE_PICKER_*` 环境变量是父子进程间传参机制，不是对外配置接口。
+
+Sources / 来源：[jiuwenswarm/channels/web/directory_picker.py:L24–L25](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/directory_picker.py#L24-L25), [jiuwenswarm/channels/web/directory_picker.py:L51–L58](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/directory_picker.py#L51-L58), [jiuwenswarm/channels/web/directory_picker.py:L296–L309](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/directory_picker.py#L296-L309)
+
+<!-- kb:knowledge owner=feature-web-native-directory-picker facet=features pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**支持的行为与边界**
+
+支持目录选择与可执行文件选择两类对话框，覆盖 Windows/macOS/Linux 三平台。取消语义统一为返回 `None`：zenity/kdialog/yad 的退出码 1、osascript stderr 中的 "User canceled"/-128、tkinter 子进程退出码 1 均映射为取消；其他非零退出码视为错误。`initial_dir` 为空或不存在时回落到 `Path.home()`。Windows 文件选择器过滤 `*.exe`（附 All files），Linux/macOS 文件后端不做扩展名过滤。
+
+Sources / 来源：[jiuwenswarm/channels/web/directory_picker.py:L118–L123](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/directory_picker.py#L118-L123), [jiuwenswarm/channels/web/directory_picker.py:L152–L159](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/directory_picker.py#L152-L159), [jiuwenswarm/channels/web/directory_picker.py:L28–L36](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/directory_picker.py#L28-L36), [jiuwenswarm/channels/web/directory_picker.py:L203–L209](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/directory_picker.py#L203-L209)
+
+<!-- kb:knowledge owner=feature-web-native-directory-picker facet=api pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**公共入口：select_directory_native 与 select_file_native**
+
+模块暴露两个公共函数。`select_directory_native(*, initial_dir: str | None = None) -> str | None` 打开本机文件夹对话框，返回选中目录的绝对路径，用户取消时返回 `None`。`select_file_native(*, initial_dir: str | None = None, title: str | None = None) -> str | None` 打开本机文件选择框，返回选中文件路径，取消同样返回 `None`；其文档字符串明确调用方负责校验所选文件在其领域内是否为可用可执行文件。两者按 `sys.platform` 分派到 win32/darwin/linux 实现，其它平台直接抛 `RuntimeError`。注意返回值并非无条件绝对路径：`_normalize_selected` 在 `resolve()` 抛异常时返回未解析的 `str(path)`。
+
+Sources / 来源：[jiuwenswarm/channels/web/directory_picker.py:L476–L505](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/directory_picker.py#L476-L505), [jiuwenswarm/channels/web/directory_picker.py:L39–L48](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/directory_picker.py#L39-L48), [jiuwenswarm/channels/web/directory_picker.py:L510–L520](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/directory_picker.py#L510-L520)
+
+<!-- kb:knowledge owner=feature-web-native-directory-picker facet=architecture pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**按平台分派的后端链与子进程隔离**
+
+两个入口各自做 `sys.platform` 分派：Windows 走进程内 tkinter 对话框（`_select_directory_windows_tk`/`_select_file_windows_tk`），macOS 通过 `_run_capture` 调用 `osascript` 独立进程，Linux 在 `_select_directory_linux`/`_select_file_linux` 中按 `shutil.which` 探测组装 zenity → kdialog → yad 后端列表，并始终追加 tkinter 子进程后端；每个后端失败（非超时）记录 warning 并继续尝试下一个，全部失败时抛带聚合错误信息的 `RuntimeError`。tkinter 子进程后端用 `subprocess.run([sys.executable, "-c", script], ...)` 直接运行内嵌脚本，通过 `JIUWEN_DIR_PICKER_*`/`JIUWEN_FILE_PICKER_*` 环境变量传参，使 `Tk()` 始终创建于子进程主线程，从而可安全地从 `asyncio.to_thread` 工作线程调用。
+
+Sources / 来源：[jiuwenswarm/channels/web/directory_picker.py:L415–L443](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/directory_picker.py#L415-L443), [jiuwenswarm/channels/web/directory_picker.py:L290–L299](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/directory_picker.py#L290-L299), [jiuwenswarm/channels/web/directory_picker.py:L339–L346](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/directory_picker.py#L339-L346), [jiuwenswarm/channels/web/directory_picker.py:L488–L493](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/directory_picker.py#L488-L493)
+
+<!-- kb:knowledge owner=feature-web-native-directory-picker facet=tradeoffs pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**跨平台后端链的取舍**
+
+以外部对话框工具的后备链换取广覆盖：zenity/kdialog/yad 按 `shutil.which` 探测、失败降级到下一后端，最终兜底为 tkinter 子进程，覆盖只装了 `python3-tk` 的 Ubuntu 桌面；代价是错误路径变长、每个后端有各自的退出码约定（zenity/kdialog/yad 退出码 1 视为用户取消）。超时不参与降级：Linux 链中 `TimeoutExpired` 直接转为 `RuntimeError("... timed out")`，不再尝试后续后端。选择在独立子进程跑 tkinter（而非工作线程内直接创建 `Tk()`）解决了线程限制，代价是每次弹窗都要启动一个 Python 解释器子进程并经环境变量/标准输出传参。
+
+Sources / 来源：[jiuwenswarm/channels/web/directory_picker.py:L418–L437](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/directory_picker.py#L418-L437), [jiuwenswarm/channels/web/directory_picker.py:L290–L295](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/directory_picker.py#L290-L295), [jiuwenswarm/channels/web/directory_picker.py:L203–L209](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/directory_picker.py#L203-L209)
+
+<!-- kb:knowledge owner=feature-web-native-directory-picker facet=validation pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b verdict=pass -->
+
+**可验证的契约：取消语义、路径规范化与平台分派**
+
+Inference / 设计推断（非作者历史意图）：
+
+本模块的验证锚点是三个可独立断言的契约。其一，取消语义在各后端统一映射为返回 None：Linux 后端（zenity/kdialog/yad）以退出码 1 表示取消（L204-L205、L217-L218），tkinter 子进程以退出码 1 表示取消（L347-L348），macOS osascript 以 stderr 中 "User canceled" 或 "-128" 判定取消（L154-L156）。其二，路径规范化契约：`_normalize_selected` 对空输入返回 None，非空输入经 strip/expanduser/resolve 处理，resolve 抛异常时回退为未解析的字符串路径（L39-L48）。其三，Linux 后端链的降级行为：单个后端非超时异常被捕获、记录 warning 后继续尝试下一个，全部失败抛聚合错误的 RuntimeError，TimeoutExpired 则不降级直接抛 RuntimeError（L427-L443）。这些契约均由所示实现直接定义，可作为针对该模块的测试断言点；本次输入未展示测试文件，无法据此说明仓库中实际的测试入口。
+
+Sources / 来源：[jiuwenswarm/channels/web/directory_picker.py:L39–L48](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/directory_picker.py#L39-L48), [jiuwenswarm/channels/web/directory_picker.py:L203–L209](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/directory_picker.py#L203-L209), [jiuwenswarm/channels/web/directory_picker.py:L152–L159](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/directory_picker.py#L152-L159), [jiuwenswarm/channels/web/directory_picker.py:L427–L443](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/directory_picker.py#L427-L443)
+
diff --git a/knowledge/repos/jiuwenswarm/components/web-frontend/feature-web-navigation.md b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-web-navigation.md
index 419dfffe..6cccdc13 100644
--- a/knowledge/repos/jiuwenswarm/components/web-frontend/feature-web-navigation.md
+++ b/knowledge/repos/jiuwenswarm/components/web-frontend/feature-web-navigation.md
@@ -10,7 +10,7 @@ sources:
 - openJiuwen-ai/jiuwenswarm@f0a69728c96b5961d993449f1a901cbd2f4dac5b:docs/zh/页面概览.md
 feature: "web-navigation"
 entry_points: ["jiuwenswarm/channels/web/frontend/src/App.tsx"]
-source_globs: ["jiuwenswarm/channels/web/frontend/src/App.tsx", "jiuwenswarm/channels/web/frontend/src/*"]
+source_globs: ["jiuwenswarm/channels/web/frontend/src/App.tsx", "jiuwenswarm/channels/web/frontend/src/*", "jiuwenswarm/channels/web/frontend/src/hooks/useAdaptiveTooltip.tsx", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/channels/ChannelsModule.tsx", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/channels/SettingsChannelsPanel.css", "jiuwenswarm/channels/web/frontend/src/components/ui/FormDrawer/FormDrawer.css", "jiuwenswarm/channels/web/frontend/src/components/ui/FormDrawer/FormDrawer.tsx", "jiuwenswarm/channels/web/frontend/src/components/ui/Input/Input.css", "jiuwenswarm/channels/web/frontend/src/components/ui/Input/Input.tsx", "jiuwenswarm/channels/web/frontend/src/components/ui/Textarea/Textarea.css", "jiuwenswarm/channels/web/frontend/src/components/ui/Textarea/Textarea.tsx", "jiuwenswarm/channels/web/frontend/index.html", "jiuwenswarm/channels/web/frontend/src/hooks/useFullscreenPanel.ts", "jiuwenswarm/channels/web/frontend/src/hooks/useHorizontalScrollEdges.ts", "jiuwenswarm/channels/web/frontend/src/components/ui/Toast/Toast.css", "jiuwenswarm/channels/web/frontend/src/components/ui/Toast/Toast.tsx", "jiuwenswarm/channels/web/frontend/src/features/settings/registry/accessPolicy.ts", "jiuwenswarm/channels/web/frontend/src/features/settings/registry/openSourceDefinition.ts", "jiuwenswarm/channels/web/frontend/src/components/ui/InfoCard/InfoCard.tsx", "jiuwenswarm/channels/web/frontend/src/components/ui/PageCard/PageCard.css", "jiuwenswarm/channels/web/frontend/src/components/ui/PageCard/PageCard.tsx", "jiuwenswarm/channels/web/frontend/src/components/ui/PageToolbarSearch/PageToolbarSearch.tsx", "jiuwenswarm/channels/web/frontend/src/components/PersonalContext/Intro.tsx", "jiuwenswarm/channels/web/frontend/src/components/PersonalContext/index.tsx", "jiuwenswarm/channels/web/frontend/src/components/ui/Select/Select.css", "jiuwenswarm/channels/web/frontend/src/components/ui/Select/Select.tsx", "jiuwenswarm/channels/web/frontend/src/features/settings/components/SettingItemRenderer.tsx", "jiuwenswarm/channels/web/frontend/src/features/settings/components/SettingRow.css", "jiuwenswarm/channels/web/frontend/src/features/settings/components/SettingRow.tsx", "jiuwenswarm/channels/web/frontend/src/features/settings/components/SettingsConfirmDialog.tsx", "jiuwenswarm/channels/web/frontend/src/features/settings/components/SettingsSection.tsx", "jiuwenswarm/channels/web/frontend/src/features/settings/settingsNavigation.ts", "jiuwenswarm/channels/web/frontend/src/features/settings/services/createSettingsRequestRouter.ts", "jiuwenswarm/channels/web/frontend/src/features/settings/services/SettingsSaveQueue.ts", "jiuwenswarm/channels/web/frontend/src/features/settings/services/SettingsServicesProvider.tsx", "jiuwenswarm/channels/web/frontend/src/features/settings/services/SettingsSourceProvider.tsx", "jiuwenswarm/channels/web/frontend/src/features/settings/services/SettingsUnsavedChangesRegistry.ts", "jiuwenswarm/channels/web/frontend/src/features/settings/services/useSettingsFormDialogClose.ts", "jiuwenswarm/channels/web/frontend/src/features/settings/services/useUnsavedChanges.ts", "jiuwenswarm/channels/web/frontend/src/components/ToolPanel/index.tsx", "jiuwenswarm/channels/web/frontend/src/main.tsx", "jiuwenswarm/channels/web/frontend/src/multi-session/routing/route.ts", "jiuwenswarm/channels/web/frontend/src/multi-session/routing/useChatRoute.ts", "jiuwenswarm/channels/web/frontend/src/components/SessionSidebar/SessionSidebar.css", "jiuwenswarm/channels/web/frontend/src/components/SessionSidebar/index.tsx", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/channels/channelAdapters.ts", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/channels/components/ChannelConfigDialog.tsx", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/channels/components/ChannelListSection.tsx", "jiuwenswarm/channels/web/frontend/src/features/settings/modules/channels/useSettingsChannelsController.ts", "jiuwenswarm/channels/web/frontend/src/features/settings/SettingsPage.css", "jiuwenswarm/channels/web/frontend/src/features/settings/SettingsPage.tsx", "jiuwenswarm/channels/web/frontend/src/features/settings/SettingsPageLayout.tsx", "jiuwenswarm/channels/web/frontend/src/features/singleAgentPanelState.ts", "jiuwenswarm/channels/web/frontend/src/features/teamPanelState.ts", "jiuwenswarm/channels/web/frontend/src/features/teamPanelStateNormalize.ts", "jiuwenswarm/channels/web/frontend/src/components/ui/Toast/toastStore.ts", "jiuwenswarm/channels/web/frontend/src/index.css"]
 ---
 
 # Web 页面与功能入口 的职责、接口与配置
diff --git a/knowledge/repos/jiuwenswarm/components/web-frontend/scripts/source-contracts-01.md b/knowledge/repos/jiuwenswarm/components/web-frontend/scripts/source-contracts-01.md
index 8e974feb..58d3fc96 100644
--- a/knowledge/repos/jiuwenswarm/components/web-frontend/scripts/source-contracts-01.md
+++ b/knowledge/repos/jiuwenswarm/components/web-frontend/scripts/source-contracts-01.md
@@ -1,7 +1,7 @@
 ---
 title: "scripts 源码接口与集成边界 01"
 created: 2026-10-01
-updated: 2026-10-01
+updated: 2026-10-06
 type: architecture
 tags: [jiuwenswarm]
 sources: []
@@ -82,3 +82,21 @@ sources: []
 
 源码依据：[完整声明与实现](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/channels/web/frontend/scripts/test-team-a2ui-render-path.mjs#L1-L65)。
 <!-- /kb:file -->
+
+<!-- kb:file path=jiuwenswarm/scripts/generate-agent-folders.js pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b sha256=92fe2b6266246a458d9d5871ea4a7645502923067fc15f378d455aa4825b126e -->
+**`jiuwenswarm/scripts/generate-agent-folders.js`**
+
+- 源码声明的类型、组件或调用边界：`fs`, `path`, `scriptDir`, `envRoot`, `agentFromEnv`, `packageAgentFromResources`, `agentRoot`, `outputPath`；这是词法声明索引，不把局部变量当成对外导出 API。
+- 集成边界的导入/加载声明：`const fs = require('fs');`；`const path = require('path');`。
+
+源码依据：[完整声明与实现](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/scripts/generate-agent-folders.js#L1-L112)。
+<!-- /kb:file -->
+
+<!-- kb:file path=jiuwenswarm/scripts/watch-folders.js pin=f0a69728c96b5961d993449f1a901cbd2f4dac5b sha256=73c7e6c086512c07a4b7038fa1bbf58a57721155ae4d9e0585982cdcecbcb01b -->
+**`jiuwenswarm/scripts/watch-folders.js`**
+
+- 源码声明的类型、组件或调用边界：`path`, `generate`, `child`, `chokidar`, `envWorkspace`, `homeDir`, `userAgentDir`, `fallbackRepoAgentDir`；这是词法声明索引，不把局部变量当成对外导出 API。
+- 集成边界的导入/加载声明：`const { spawn } = require('child_process');`；`const path = require('path');`；`const chokidar = require('chokidar');`。
+
+源码依据：[完整声明与实现](https://github.com/openJiuwen-ai/jiuwenswarm/blob/f0a69728c96b5961d993449f1a901cbd2f4dac5b/jiuwenswarm/scripts/watch-folders.js#L1-L48)。
+<!-- /kb:file -->