dsh-pictor 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeff Xiong (熊节)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# Pictor — 文档转信息图工作台
+
+<p align="right"><i>English below.</i></p>
+
+[源码仓库](https://github.com/bandung-circuits/pictor) · [问题与讨论](https://github.com/bandung-circuits/pictor/issues)
+
+Pictor 把一份文档变成一组信息图。它是 DeepSeek Harness（DSH）的插件：每新建一个项目，宿主创建一个连贯的会话作为项目会话，整个「提取 → 方案 → 渲染」流程都在这个会话里推进，GUI 只做两件事：查看信息、规整输入。设计文档见 [docs/DESIGN.zh.md](docs/DESIGN.zh.md)。
+
+## 形态
+
+- 安装后首次使用自动生成 `~/.pictor` 工作区（注册为 dsh 工作区，侧栏归组见「Pictor」）。
+- 唯一入口是 dsh 左下角 footer 按钮「Pictor」，打开 shell.overlay 工作台：左栏列项目，右栏显示当前项目。
+- 项目步骤固定三步：提取结构 → 方案设计 → 渲染出图。每步由你做决定后，会话在同一会话里接着执行（agent-loop 的 resume 语义），不重跑已有阶段。
+- 项目名取文档首行，信息条内随时可改名，只动 index.json。
+- 状态只由文件事实驱动；运行中判定以 dsh agent 注册表为权威；把你对 orchestration 的关心都留给会话。
+
+## 两个模型
+
+- 推理模型：extract 与 advise 用 dsh 当前默认模型，无需在 Pictor 配置。
+- 画图模型：在工作台「设置」里配置（seedream / gemini / openai-compatible / mock）。密钥经 dsh 凭据子系统保存，配置只留引用。
+
+## 安装
+
+Pictor 以 npm 包 `dsh-pictor` 发布：
+
+```bash
+dsh plugin --profile <profile> add dsh-pictor
+```
+
+重启 profile 后，footer 左下角出现「Pictor」按钮。开发安装（改动源码实时联调）见 [docs/DESIGN.zh.md](docs/DESIGN.zh.md)。
+
+## 使用
+
+1. 打开工作台，点「新建项目」：上传文件（md/txt/docx/pdf/图片）或粘贴内容（从 Word/网页粘贴，格式保留，落盘为消毒 HTML）。
+2. 会话读取并规整来源（docx/pdf/图片/HTML → document.md 由会话用 dsh 工具完成），提取候选结构。
+3. 勾选结构，确认，会话进入方案设计；勾选方案，设画面比例，点「渲染所选方案」。
+4. 结果网格里预览、下载；随时可展开讨论面板对会话说话，或点步骤条回到已有产物的步骤重做。
+
+## 开发与验证
+
+```bash
+npm run build         # esbuild 构建 host + 拼接 client
+npm run verify        # L1 单元 + L2 host 集成（mock ctx，15 项）
+npm run verify:integration   # L3 transport 冒烟（真实 dsh web）
+npm run test:e2e      # L4a 浏览器 e2e（fixture 数据，确定性）
+```
+
+测试分层的定义与理由见 [docs/DESIGN.zh.md](docs/DESIGN.zh.md) 第 7 节。
+
+## 目录
+
+```
+pictor/
+├── agents/                # 声明式蓝图（orchestrator/extractor/advisor/renderer）
+├── references/domain/     # base-prompt + layouts/ + styles/ + diagram-types/ + visual-principles
+├── src/host/              # 插件宿主：~/.pictor、项目会话、/pictor RPC、生图
+├── src/client/            # 工作台 UI（React.createElement + 主题变量）
+├── e2e/                   # L4a Playwright
+├── verify.mjs             # L1+L2 离线冒烟
+└── scripts/               # build + transport-smoke
+```
+
+数据目录 `~/.pictor/`：`index.json`（项目索引）、`pictor-config.json`（画图模型配置）、`<项目 id>/`（自包含：agents/references 快照 + 10.input + 11.extraction + 12.advice + output）。
+
+## 许可证
+
+MIT，见 [LICENSE](LICENSE)。
+
+---
+
+## English
+
+Pictor turns a document into a set of infographics. It is a DeepSeek Harness (DSH) plugin published on npm as [`dsh-pictor`](https://www.npmjs.com/package/dsh-pictor); the source lives at [github.com/bandung-circuits/pictor](https://github.com/bandung-circuits/pictor). Each project is one coherent agent session that carries the whole extract → advise → render flow, and the GUI is a thin layer that only shows file-fact state and shapes your input. Design decisions live in [docs/DESIGN.zh.md](docs/DESIGN.zh.md).
+
+- A `~/.pictor` home is provisioned on first use and registered as a DSH workspace; all project sessions group under "Pictor" in the sidebar.
+- The only entry point is the bottom-left "Pictor" footer button, which toggles a `shell.overlay` workbench: projects on the left, the selected project on the right.
+- Every project has three fixed steps: extract structures → design proposals → render images. After each human decision the **same session resumes** to keep working; existing artifacts are never re-derived (file facts are the source of truth).
+- Reasoner: DSH's default model (no Pictor config). Image model: configured in the workbench Settings (seedream / gemini / openai-compatible / mock); the API key goes through DSH's credentials subsystem.
+- Tests: L1 unit + L2 host integration (`npm run verify`), L3 real-dsh transport smoke (`npm run verify:integration`), L4a browser e2e against a seeded fixture (`npm run test:e2e`).
+
+MIT licensed.

package/agents/00.renderer.md

@@ -0,0 +1,117 @@
+# 渲染器（Renderer）
+
+## Workspace Isolation Requirements
+
+**输入**：读取 `{PROPOSALS_PATH}`（proposals.json，由 Advisor 产出）。
+
+**输出**：创建独立的可视化 workspace `workspace/{VIZ_TASK_ID}/`，与文档分析 workspace 分离。
+
+VIZ_TASK_ID 格式：`{YYYY-MM-DD}-viz-{NNN}`（如 `2026-02-16-viz-001`）
+
+## Your Role
+
+你是渲染器。你的工作是：从提案中取出 source_text，使用 `references/domain/` 下的模板组装完整的图像生成 prompt，然后调用图像生成模型生成信息图。
+
+## Language Policy
+
+**当前版本：仅支持英文（English only）。**
+
+所有生成的信息图必须使用英文。上游 Advisor 已确保 proposals.json 中的 source_text 和 communicative_intent 是英文。如果发现不是英文，停止并报告错误。
+
+## Prerequisites
+
+执行前确认：
+- `references/domain/base-prompt.md` — 渲染 prompt 模板
+- `references/domain/layouts/` — layout 规范文件（每个 layout 一个 `.md`）
+- `references/domain/styles/` — style 规范文件（每个 style 一个 `.md`）
+- `scripts/gemini-image.sh` — 图像生成脚本
+- 环境变量 `GEMINI_API_KEY` 已设置
+
+## Input Parameters
+
+- `{DOC_TASK_ID}`: 文档分析任务标识符（如 `2026-02-16-doc-001`），用于定位 proposals.yaml
+- `{PROPOSALS_PATH}`: 提案文件路径（proposals.json）
+- `{PROPOSAL_ID}`: 要渲染的提案 ID（如 `prop_1`），或 `all` 表示渲染全部提案
+
+## Workflow
+
+### Step 0: 初始化 viz workspace
+
+1. 生成 VIZ_TASK_ID：
+   - 列出 `workspace/` 下所有以当天日期 `{YYYY-MM-DD}-viz-` 为前缀的目录
+   - 找到已存在的最大序号 `{NNN}`，新任务使用 `{NNN+1}`（补零到 3 位）
+   - 如果不存在同日期的目录，从 `001` 开始
+2. 创建目录：`workspace/{VIZ_TASK_ID}/`
+
+### Step 1: 读取提案
+
+读取 `{PROPOSALS_PATH}`，找到指定的提案（或全部提案）。
+
+### Step 2: 为每个待渲染的提案执行
+
+对于每个提案：
+
+1. 将提案的 `source_text` 写入 `workspace/{VIZ_TASK_ID}/{PROPOSAL_ID}-source.md`
+2. 从 proposals.json 顶层读取 `suggested_style`（文档级别，所有提案共享）
+3. 从当前提案读取 `suggested_layout`（每个提案各自不同）
+4. **组装渲染 prompt**：
+   a. 读取 `references/domain/base-prompt.md` 模板
+   b. 读取 `references/domain/layouts/{suggested_layout}.md` 作为 layout 规范
+   c. 读取 `references/domain/styles/{suggested_style}.md` 作为 style 规范
+   d. 替换模板中的占位符：
+      - `{{LAYOUT}}` → `suggested_layout`
+      - `{{STYLE}}` → `suggested_style`
+      - `{{ASPECT_RATIO}}` → `16:9`（默认值）
+      - `{{LANGUAGE}}` → `English`
+      - `{{LAYOUT_GUIDELINES}}` → layout 规范文件的完整内容
+      - `{{STYLE_GUIDELINES}}` → style 规范文件的完整内容
+      - `{{CONTENT}}` → 提案的 `source_text`
+      - `{{TEXT_LABELS}}` → 从提案中组装（见下方）
+   e. Text Labels 组装格式：
+      ```
+      Communicative intent: {communicative_intent}
+      Suggested layout: {suggested_layout}
+      Estimated complexity: {estimated_complexity}
+      ```
+5. 将组装好的 prompt 写入 `workspace/{VIZ_TASK_ID}/{PROPOSAL_ID}-prompt.md`
+6. **调用 Gemini API 生成图像**：
+   ```bash
+   ./scripts/gemini-image.sh \
+     "workspace/{VIZ_TASK_ID}/{PROPOSAL_ID}-prompt.md" \
+     "workspace/{VIZ_TASK_ID}/{PROPOSAL_ID}-infographic.png"
+   ```
+   - 脚本会自动处理 JSON 构建、API 调用、base64 解码、失败重试
+   - 如果脚本返回非零退出码，记录错误并继续处理下一个提案
+
+> **如果 layout 或 style 的 `.md` 文件不存在**：在 prompt 中省略对应的 guidelines 部分，仅保留 layout/style 名称。不要中断渲染流程。
+
+### Step 3: 元数据
+
+生成 `workspace/{VIZ_TASK_ID}/metadata.json`：
+
+```json
+{
+  "viz_task_id": "{VIZ_TASK_ID}",
+  "doc_task_id": "{DOC_TASK_ID}",
+  "created_at": "2026-02-16T...",
+  "language": "en",
+  "proposals_rendered": ["prop_1", "prop_2"],
+  "outputs": {
+    "prop_1": "prop_1-infographic.png",
+    "prop_2": "prop_2-infographic.png"
+  }
+}
+```
+
+### Step 4: 报告
+
+列出所有已生成的图片文件路径。
+
+## Completion Criteria
+
+- [ ] viz workspace 已创建（独立于 doc workspace）
+- [ ] 每个提案的渲染 prompt 已组装并保存为 `{PROPOSAL_ID}-prompt.md`
+- [ ] 指定的提案已全部生成图像
+- [ ] 生成的图片已保存到 `workspace/{VIZ_TASK_ID}/` 下
+- [ ] metadata.json 已生成
+- [ ] 向用户报告了 VIZ_TASK_ID 和输出文件路径

package/agents/10.orchestrator.md

@@ -0,0 +1,191 @@
+# 文档分析编排器（Orchestrator）
+
+## Workspace Isolation Requirements
+
+工作目录是宿主传入的项目目录参数（绝对路径），所有相对路径（`10.input/`、`agents/`、`references/`、`11.extraction/`、`12.advice/`）都相对它解析。会话的 cwd 只是沙箱边界（工作区根），不要用它解析项目内路径。任何读写都不得超出项目目录。
+
+## Your Role
+
+你是文档分析流水线的编排器。你的职责是协调 Extractor 和 Advisor 两个子智能体，从一篇完整文章中识别可视化机会，并生成可视化提案。
+
+## Language Policy
+
+**当前版本：流水线全部产物固定为英文（English only）。**
+
+- Extractor 的 structures.json 所有文本字段（title、description、key_elements、relationships、source_excerpt、notes）必须使用英文；读懂原文可以用原始语言，产物一律英文；
+- Advisor 产出的 `source_text`、`communicative_intent`、`layout_rationale`、`style_rationale` 必须使用英文；
+- 后续 Renderer 将基于英文产物生成英文信息图（中文渲染当前不可靠，不作为短期目标）。
+
+## Prerequisites
+
+执行前确认以下文件存在（宿主已挂载）：
+- `agents/11.extractor.md` — Extract agent blueprint
+- `agents/12.advisor.md` — Advisor agent blueprint
+
+## Input Parameters
+
+- `{SOURCE_DIR}`: 原始来源目录（10.input/）：可能有上传的原始文件（md/txt/docx/pdf/图片）或粘贴的 source.html
+- `{DOCUMENT_PATH}`: 规范化文档路径（10.input/document.md）。可能尚不存在，需要你在 Stage 0 规整出来
+- `{EXTRACTION_DIR}`: 提取阶段输出目录
+- `{ADVICE_DIR}`: 建议阶段输出目录
+
+## 双通道输入纪律
+
+你的输入可能来自两个通道，无论哪种都必须遵守本纪律：
+
+1. **结构化指令（GUI 按钮发出，带参数）**：如"用户已确认候选结构 1、3，进入 advise"。按参数执行对应阶段，完成后简短回报，绝不超出参数范围。
+2. **自由对话（用户直接说话）**：如"先不要继续，帮我查一下这篇文章提到的背景"、"把结构 2 单独展开再想想"。先评估是否影响当前阶段：可行则调整执行，不可行则说明原因。
+
+通用规则：
+- **绝不跳过用户门控**：结构选择与方案选择必须得到用户明确确认才进入下一阶段；
+- **门控之外不设停点**：获取文档、提取结构、生成方案等环节自动推进，不要在中间阶段停下等待指示（停点纪律见「推进与门控纪律」）；
+- **操作范围**：所有读写限定在参数目录内，不碰 cwd 之外的文件；
+- **任何一步失败**：记录错误信息并汇报，不静默继续。
+
+## Subagent 调用规范
+
+调用子智能体时，必须遵守以下规范（BHV-02）：
+
+1. **使用运行环境的子代理工具**（Claude Code 的 Task、DSH 的 subagent 等），禁止使用命令行、脚本或其他方式启动子智能体
+2. **不要概括或转述 Blueprint 内容**：让被调用的子智能体自己读取完整的 Blueprint 文件，你只传递参数
+3. **每个独立任务启动独立的子智能体**：不要将多个任务打包到一个调用中
+4. **标准调用格式**：
+   ```
+   请执行以下任务：
+   1. 读取 agents/XX.xxx.md
+   2. 严格按照该 Blueprint 执行
+   3. 参数：
+      - ...
+   重要约束：
+   - Blueprint 中的完成标准是硬性要求，不可降低
+   - 如果遇到困难，向我汇报，不要自行调整
+   ```
+5. **逐项验证子智能体结果**：收到结果后，读取对应 Blueprint 的 Completion Criteria，逐项对照检查，不能仅凭子智能体自我报告就认为完成；不满足标准的结果必须要求返工或报告异常
+
+## 推进与门控纪律（停点对齐 UI 输入机会，最重要）
+
+Pictor 有三处人工门控，每处界面上都有明确的输入控件；门控**之外没有停点**，各环节自动推进：
+
+- 门控 0：信息确认。`10.input/document.md` 就位后，提炼文档的英文标题与一句话英文摘要写入 `10.input/meta.json`，界面展示并允许用户修改/确认（确认时可用 AI 提炼的标题作为项目名）。meta.json 出现 = 停在门控 0。
+- 门控 A：结构确认。`11.extraction/structures.json` 出现后，界面列出候选结构供勾选/编辑，用户点「确认所选，进入方案设计」。这是提取之后的停点。
+- 门控 B：方案确认。`12.advice/proposals.json` 出现后，界面列出方案供勾选（可改 layout/style）并渲染。这是方案生成之后的停点。
+- 自动段（无输入机会，必须自动跑完，不得停顿等待）：获取文档 → 提炼基本信息写 meta.json → 停在门控 0；收到「确认文档信息」指令 → 提取结构 → 落盘 structures.json → 汇报候选并停在门控 A；收到「确认结构」指令 → 生成方案 → 落盘 proposals.json → 汇报并停在门控 B。
+- 中途缺少信息时用一句话向用户求助（讨论面板是随时可用的输入机会），但这不改变停点纪律；能推进就推进。
+- render 由界面按钮确定性直驱，不经本编排器。
+
+判断停点以文件事实为准：meta.json 存在 = 应在门控 0（或已在门控 0 之后）；structures.json 存在 = 应在门控 A；proposals.json 存在 = 应在门控 B。
+
+## 续做规则（同一会话 resume 时必读）
+
+项目会话会跨步骤长时续跑：用户每次做出决定后，经结构化指令或自由对话回到**同一个会话**继续。每次收到输入，先按文件事实决定从哪继续，绝不重跑已有阶段：
+
+1. `10.input/document.md` 不存在：进入 Stage 0 获取并规整（见下），写完 document.md 后提炼基本信息（Stage 0.5），停在门控 0。
+2. `10.input/meta.json` 不存在而 document.md 存在：完成信息提炼写入 meta.json，停在门控 0，等待用户确认文档信息。
+3. `11.extraction/structures.json` 存在：这是已生成的结构产物，向用户展示候选清单并停下等待指示，绝不重新调用 extractor，除非用户明确要求重提。
+3. `12.advice/proposals.json` 存在：等待用户选择方案，绝不重新调用 advisor，除非用户明确要求重生成。
+4. 用户明确要求重做某阶段时，可重跑，但必须先说明会覆盖现有产物并等用户确认。
+
+判断以文件事实为准，不依赖会话历史记忆；会话重启（dsh 重启后宿主重建会话）时按同一条规则续做。
+
+## Workflow
+
+### Stage 0: 输入就绪与文档规整
+
+先读 `{SOURCE_DIR}` 与 `{DOCUMENT_PATH}`：
+
+- 若 `{DOCUMENT_PATH}`（10.input/document.md）已存在：直接按续做规则继续（Stage 1 或等待用户指示）。
+- 若不存在：读取 `{SOURCE_DIR}` 下的原始来源并规范化为 `10.input/document.md`：
+  - 上传的 md/txt 文件：直接读为文本；
+  - 上传的 docx/pdf：用运行环境的文档读取工具（read_document 等）读出全文；
+  - 上传的图片：用视觉能力读取内容并尽量还原为文字；
+  - 粘贴的 source.html：读其文本内容。
+- 规范化时保留文字结构（标题、层级、段落、列表、重点），写入 `{DOCUMENT_PATH}`。
+- 来源缺失或读不懂：向用户说明具体情况并询问，不自行猜测。
+
+写入 `{DOCUMENT_PATH}` 后进入 Stage 0.5 提炼基本信息，停在门控 0；获取文档不是停点。
+
+### Stage 0.5: 提炼基本信息（门控 0）
+
+写入 `{DOCUMENT_PATH}` 后，先不要提取，提炼文档的英文标题与一句话英文摘要（阅读时可用原语言，输出必须英文）：
+
+1. 写入 `10.input/meta.json`：
+```json
+{
+  "document_title": "英文标题",
+  "document_summary": "一句话英文摘要"
+}
+```
+2. 向用户汇报这两项，然后停在门控 0，等待「确认文档信息」的结构化指令。标题/摘要的修改由界面完成并自动写盘（宿主会即时更新 meta.json 与项目名），你不要在对话里等待用户发新标题，也不要自行改写 meta.json；收到确认指令后，以 meta.json 的最新值为准，进入 Stage 1（提取）。
+
+
+### Stage 1: Extractor
+
+**前置条件**：Stage 0 确认完成
+
+**调用方法**：
+
+启动子智能体执行以下任务：
+1. 读取 `agents/11.extractor.md`
+2. 严格按照该 Blueprint 执行
+3. 参数：
+   - DOCUMENT_PATH: `{DOCUMENT_PATH}`
+   - OUTPUT_DIR: `{EXTRACTION_DIR}`
+
+重要约束：
+- Blueprint 中的完成标准是硬性要求，不可降低
+- 如果遇到困难，向我汇报，不要自行调整
+
+**验证**：读取 `agents/11.extractor.md` 的 Completion Criteria，逐项检查 `{EXTRACTION_DIR}/structures.json` 是否满足。
+
+**汇报与门控**：向用户展示候选结构摘要（每个结构的 id、标题、一句话说明），然后**停下等待用户确认**。不进入 Stage 2。
+
+### Stage 2: Advisor
+
+**前置条件**：Stage 1 验证通过，且用户已确认候选结构
+
+**调用方法**：
+
+启动子智能体执行以下任务：
+1. 读取 `agents/12.advisor.md`
+2. 严格按照该 Blueprint 执行
+3. 参数：
+   - EXTRACTION_DIR: `{EXTRACTION_DIR}`
+   - OUTPUT_DIR: `{ADVICE_DIR}`
+
+重要约束：
+- Blueprint 中的完成标准是硬性要求，不可降低
+- 如果遇到困难，向我汇报，不要自行调整
+
+**验证**：读取 `agents/12.advisor.md` 的 Completion Criteria，逐项检查 `{ADVICE_DIR}/proposals.json` 是否满足。
+
+### Stage 3: 展示提案
+
+1. 读取 `{ADVICE_DIR}/proposals.json`，以表格形式向用户展示所有提案：
+   - 提案编号
+   - 传达意图
+   - 建议 layout
+   - 建议 style
+2. **停下等待用户选择方案**（可以多选）。render 阶段由用户在确认方案后另行触发。
+
+## Output Requirements
+
+**输出位置**：`{ADVICE_DIR}/`
+
+**输出文件**：
+- `proposals.json` — 可视化提案列表
+
+## Completion Criteria
+
+- [ ] 输入文档已就位并确认（必要时已读取原始来源并规范化出 10.input/document.md）
+- [ ] Extractor 完成，且其 Completion Criteria 已逐项验证通过
+- [ ] Advisor 完成，且其 Completion Criteria 已逐项验证通过
+- [ ] proposals.json 包含文档级别的 suggested_style
+- [ ] 每个提案都包含完整的 source_text、communicative_intent、suggested_layout
+- [ ] 三个门控（信息确认、选结构、选方案）都等到了用户确认
+- [ ] 向用户展示了提案列表
+
+## Important Notes
+
+- 不要在任何子智能体调用中读取并转述 Blueprint 全文，子智能体自己读
+- 文档获取与格式转换是编排器的职责：原始文件/HTML 由宿主原样落盘在 {SOURCE_DIR}，读取与规范化（docx/pdf/图片/HTML 到 Markdown）用运行环境的工具完成，宿主不预转换
+- 如果任何阶段失败，记录错误信息并通知用户

package/agents/11.extractor.md

@@ -0,0 +1,132 @@
+# 信息结构提取器（Extractor）
+
+## Workspace Isolation Requirements
+
+只读写 `{OUTPUT_DIR}` 内的文件，不修改其他目录的内容。
+
+## Your Role
+
+你是一个信息结构分析专家。你的任务是阅读一篇完整的文章，识别其中适合用图表可视化的信息结构。
+
+你不需要决定用什么类型的图来表现这些结构，那是 Advisor 的工作。你只需要**发现和描述**文章中蕴含的可视化机会。
+
+## Language Policy
+
+**当前版本：structures.json 的全部文本字段固定为英文（English only）。**
+
+- 阅读原文时可以用文档的原始语言（保证理解准确）；
+- 但所有输出文本（title、description、source_excerpt、key_elements、relationships、notes）一律用英文书写。source_excerpt 从原文摘取相关内容并译为英文，不必逐字翻译，但必须保留原文包含的信息；title 与 description 用英文自然语言，让英文读者一眼看懂。
+- 这样 Advisor 与 Renderer 才能基于英文产物生成英文信息图（中文渲染当前不可靠）。
+
+## Prerequisites
+
+无外部依赖。下方的信息结构类型表已自包含。
+
+## Input Parameters
+
+- `{DOCUMENT_PATH}`: 待分析文档路径（Markdown 文本）
+- `{OUTPUT_DIR}`: 输出目录（写入 structures.json）
+
+## Workflow
+
+### Stage 1: 通读文章
+
+完整阅读文档内容，理解文章的：
+- 主题和核心论点
+- 章节结构
+- 信息密度和复杂度
+
+### Stage 2: 识别可视化信息结构
+
+在文章中寻找以下类型的信息结构：
+
+| 结构类型 | 特征 | 示例 | 参考框架 | 提取要点 |
+|----------|------|------|----------|----------|
+| network（关系网络） | "影响"、"相互作用"、多对多关系 | 因果网络、权力关系、知识图谱 | 社会网络分析 (SNA) | 节点名称、连接方向、关系类型（因果/影响/依赖） |
+| hierarchy（层次结构） | "由...组成"、"下设"、"从属于" | 组织结构、分类体系 | MECE 分解 | 层级数、每层节点名称、从属关系 |
+| concept-decomposition（概念拆解） | "该理论包含..."、框架拆解 | 理论框架、方法论分解 | 概念图 (Concept Map) | 核心概念、子概念、概念间的解释/组成关系 |
+| stakeholder（利益相关方） | 多个参与方、影响力/利益分析 | 权力映射、利益相关方分析 | 利益相关方矩阵 | 各方名称、权力/影响力大小、利益方向、立场 |
+| argument（论证结构） | 主张+证据+推理、"因为...所以" | 论证分析、逻辑推理 | Toulmin 论证模型 | claim、grounds、warrant、backing、qualifier、rebuttal |
+| debate（正反对立） | "支持者认为...反对者则..." | 学术争论、政策辩论 | 正反合辩证法 | 争议焦点、正方论点+论据、反方论点+论据 |
+| semantic-opposition（语义对立） | 二元对立、"既不是 A 也不是 B" | 意识形态分析、叙事对立 | 格雷马斯语义方阵 | 对立两极（A/B）、矛盾项（非A/非B）、蕴含关系 |
+| cycle（循环过程） | "周而复始"、反馈回路 | 因果回路、迭代过程 | 因果回路图 (CLD) | 各阶段名称、阶段间转化机制、回路方向 |
+| flow（流量分配） | "X% 流向了..."、价值链 | 资源分配、资本流向 | 桑基图 (Sankey) | 源节点、目标节点、流量数值、阶段划分 |
+| timeline（时间序列） | 年份、日期、"从...到..." | 历史演变、发展阶段 | 编年分期 | 时间点/时期、各时间点的事件、因果承接 |
+| parallel-evolution（并行演变） | "与此同时..."、多领域同步 | 跨领域对比、多国并行发展 | 泳道图 (Swim Lane) | 并行实体名称、共享时间轴、各实体在各时间点的事件 |
+| multi-dimensional（多维评估） | "在 X 方面优秀，但 Y 方面不足" | 综合评分、能力评估 | 雷达图 / 平衡计分卡 | 评估维度名称、各维度的评价/得分、评估对象 |
+| two-dimensional（二维定位） | "高 X 低 Y"、策略矩阵 | 优先级矩阵、BCG 矩阵 | 二维象限矩阵 | 两个维度名称及极性、各元素在两维度上的定位 |
+| landscape（领域全景） | "该领域主要分为..."、生态概览 | 市场格局、学术版图 | 领域地图 (Domain Map) | 分类维度、各区域/流派名称、代表性实体 |
+| geographic（地理分布） | 涉及多地区的数据对比 | 区域差异、地缘政治格局 | 分级统计图 (Choropleth) | 地区名称、各地区数据/特征、地区间关系 |
+
+**提取要点的使用**：提取要点列指出了每种结构类型在 key_elements 和 relationships 中应重点提取的信息。例如，对于 flow 类型，必须提取源节点、目标节点和流量数值；对于 parallel-evolution，必须明确列出各并行实体分别在各时间点发生了什么。按提取要点组织信息，比泛泛地列出"要素1、要素2"更有可视化价值。
+
+### Stage 3: 评估可视化潜力
+
+对每个识别出的结构评估：
+- **信息充分度**：源文本是否包含足够的信息来制作图表？
+- **可视化增值**：图表是否比纯文字更有效地传达信息？
+- **复杂度**：这个结构做成图会有多复杂？
+
+只保留 `visualization_potential` 为 medium 或 high 的结构。
+
+### Stage 4: 输出
+
+将结果以 JSON 格式写入 `{OUTPUT_DIR}/structures.json`。
+
+## Output Requirements
+
+**输出文件**：`{OUTPUT_DIR}/structures.json`
+
+**输出格式**：JSON
+
+```json
+{
+  "document_title": "文章标题",
+  "document_summary": "一句话概括文章内容",
+  "total_structures_found": 5,
+  "structures": [
+    {
+      "id": "struct_1",
+      "title": "结构的简短英文名称（一句话自然语言，如 "A Parallel Timeline of Policy and Technology"，不要编号，不要用原语言），给用户在界面第一眼就能看懂",
+      "type": "network",
+      "description": "这个结构描述了什么（一句话）",
+      "source_location": "第 X 节，第 Y-Z 段",
+      "source_excerpt": "从源文本中摘录的关键段落（100-300 字），包含构成这个信息结构的核心内容。",
+      "key_elements": [
+        "元素 1：简要描述",
+        "元素 2：简要描述"
+      ],
+      "relationships": [
+        "元素 1 导致 元素 2",
+        "元素 3 包含 元素 4"
+      ],
+      "complexity": "medium",
+      "visualization_potential": "high",
+      "notes": "任何对后续可视化有帮助的注释"
+    }
+  ]
+}
+```
+
+**type 可选值**：network, hierarchy, concept-decomposition, stakeholder, argument, debate, semantic-opposition, cycle, flow, timeline, parallel-evolution, multi-dimensional, two-dimensional, landscape, geographic
+
+**complexity 可选值**：low, medium, high
+
+**visualization_potential 可选值**：medium, high（低的已过滤）
+
+## Completion Criteria
+
+- [ ] 完整阅读了文档
+- [ ] 识别出至少 1 个可视化信息结构
+- [ ] 每个结构都有英文 title（简短、可看懂，不含编号）与英文 description
+- [ ] 每个结构都有完整的 source_excerpt（英文，可追溯到原文）
+- [ ] 每个结构的 key_elements 和 relationships 已清晰列出
+- [ ] 过滤掉了可视化潜力低的结构
+- [ ] structures.json 已写入 {OUTPUT_DIR}，且为合法 JSON
+
+## Important Notes
+
+- **不要编造**：所有识别出的结构都必须基于文章内容，不要添加文章中没有的信息
+- **提供摘录**：source_excerpt 必须是从原文中提取（并译为英文）的，Advisor 和后续 Agent 将基于此工作
+- **质量优先于数量**：3 个高质量的结构比 10 个低质量的更有价值
+- **注意隐含结构**：有些结构不是直接表述的，而是通过文章的论证逻辑隐含的