create-windy 0.8.2 → 0.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-windy",
-  "version": "0.8.2",
+  "version": "0.9.1",
   "description": "创建单组织、单租户、私有部署优先的 Windy 企业 Dashboard Starter",
   "type": "module",
   "bin": {

package/template/.windy-template.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "templateCommit": "7c00e145cc8fef9f4c6ec621e8740e3c01f7cc2d",
-  "generatorVersion": "0.8.2",
+  "templateCommit": "65f35a9b300c836eafca56da477238edb0ee1cde",
+  "generatorVersion": "0.9.1",
   "modules": [
     {
       "name": "system",

package/template/apps/agent-server/Dockerfile

@@ -1,27 +1,97 @@
 # syntax=docker/dockerfile:1
+# One application-owned Agent Server image; DSH is an npm workspace dependency.
+FROM oven/bun:1.3.14-slim@sha256:d56a2534ffd262e92c12fd3249d3924d296d97086da773f821d7d0477435ea04 AS bun
+FROM node:24.7.0-bookworm-slim@sha256:0104d9447ea3ddf7373643be7f9915fc7b7c896e41d0d33229338e457217cd78 AS node
+FROM bun AS dependencies
+WORKDIR /app
+COPY package.json bun.lock ./
 
-FROM python:3.12-slim AS runtime
-WORKDIR /app/apps/agent-server
-
-ARG WINDY_PYPI_INDEX_URL=http://mirrors.cloud.tencent.com/pypi/simple
-ARG WINDY_PYPI_TOTAL_TIMEOUT_SECONDS=180
+# windy-copy:deps begin
+COPY apps/agent-server/package.json apps/agent-server/package.json
+COPY apps/license/package.json apps/license/package.json
+COPY apps/server/package.json apps/server/package.json
+COPY apps/signing-service/package.json apps/signing-service/package.json
+COPY apps/web/package.json apps/web/package.json
+COPY apps/windy-gateway/package.json apps/windy-gateway/package.json
+COPY packages/ai-client/package.json packages/ai-client/package.json
+COPY packages/config/package.json packages/config/package.json
+COPY packages/create-windy/package.json packages/create-windy/package.json
+COPY packages/crud-generator/package.json packages/crud-generator/package.json
+COPY packages/database/package.json packages/database/package.json
+COPY packages/delivery/package.json packages/delivery/package.json
+COPY packages/example-work-order/package.json packages/example-work-order/package.json
+COPY packages/jobs/package.json packages/jobs/package.json
+COPY packages/license-sdk/package.json packages/license-sdk/package.json
+COPY packages/model-gateway/package.json packages/model-gateway/package.json
+COPY packages/modules/package.json packages/modules/package.json
+COPY packages/server-sdk/package.json packages/server-sdk/package.json
+COPY packages/shared/package.json packages/shared/package.json
+COPY packages/storage/package.json packages/storage/package.json
+# windy-copy:deps end
+# Other platforms and unused audio engines are excluded. Install the fixed
+# Debian prerequisites and Office WASM engine against this workspace lock.
+RUN --mount=type=cache,id=windy-agent-bun-1.3.14,target=/root/.bun/install/cache,sharing=shared \
+    bun install --frozen-lockfile --filter @southwind-ai/agent-server --production --ignore-scripts --omit=optional --linker=hoisted
+COPY apps/agent-server/install-native.ts apps/agent-server/native-download.ts /opt/
+ARG WINDY_AGENT_NATIVE_REGISTRY=https://registry.npmjs.org
+RUN --mount=type=cache,id=windy-agent-native-v1,target=/root/.cache/windy-agent-native,sharing=locked \
+    DSH_NATIVE_CACHE_DIR=/root/.cache/windy-agent-native DSH_NATIVE_REGISTRY=$WINDY_AGENT_NATIVE_REGISTRY bun /opt/install-native.ts
+# Keep the complete upstream engine package, including sources/, licenses/ and
+# prebuilds.json. Office conversion never downloads an engine at runtime.
+FROM dependencies AS build
+COPY packages packages
+COPY apps/agent-server apps/agent-server
+RUN bun run --cwd apps/agent-server build
 
-COPY apps/agent-server/install-python-dependencies.sh /usr/local/bin/windy-agent-python-install
-RUN chmod 0755 /usr/local/bin/windy-agent-python-install \
-  && windy-agent-python-install install-uv \
-  && useradd --create-home --uid 10001 windy
-COPY apps/agent-server/pyproject.toml apps/agent-server/uv.lock ./
-RUN windy-agent-python-install lock
-RUN windy-agent-python-install sync --frozen --no-dev --no-install-project
-COPY apps/agent-server/src ./src
-RUN windy-agent-python-install sync --frozen --no-dev
+FROM scratch AS fonts
+ADD --checksum=sha256:4a2515eb6db3978b897fef9709ed0d2b1f4c6c4df4d83d6c4ef65f71f1b1f502 \
+    https://deb.debian.org/debian/pool/main/f/fonts-noto-cjk/fonts-noto-cjk_20220127+repack1-1_all.deb /fonts.deb
+FROM python:3.12.12-slim-bookworm@sha256:593bd06efe90efa80dc4eee3948be7c0fde4134606dd40d8dd8dbcade98e669c AS document-wheels
+ARG WINDY_PYPI_INDEX_URL=https://pypi.org/simple
+ARG WINDY_PYPI_TOTAL_TIMEOUT_SECONDS=600
+COPY deploy/dsh/documents/requirements.lock /requirements.lock
+RUN --mount=type=cache,target=/root/.cache/pip \
+    test "$WINDY_PYPI_TOTAL_TIMEOUT_SECONDS" -ge 1 && test "$WINDY_PYPI_TOTAL_TIMEOUT_SECONDS" -le 600 && \
+    timeout --kill-after=5s "$WINDY_PYPI_TOTAL_TIMEOUT_SECONDS" pip download \
+      --index-url "$WINDY_PYPI_INDEX_URL" --timeout 30 --retries 2 \
+      --require-hashes --only-binary=:all: -r /requirements.lock --dest /wheels
 
-ENV PATH="/app/apps/agent-server/.venv/bin:${PATH}"
-ENV PYTHONUNBUFFERED=1
+FROM python:3.12.12-slim-bookworm@sha256:593bd06efe90efa80dc4eee3948be7c0fde4134606dd40d8dd8dbcade98e669c AS runtime
+WORKDIR /app/apps/agent-server
+ARG WINDY_DEBIAN_MIRROR=http://deb.debian.org/debian
+ARG WINDY_DEBIAN_SECURITY_MIRROR=http://deb.debian.org/debian-security
+RUN --mount=type=cache,id=windy-agent-apt,target=/var/cache/apt,sharing=locked \
+    set -eu; \
+    echo "$WINDY_DEBIAN_MIRROR" | grep -Eq '^https?://[A-Za-z0-9./:_-]+$'; \
+    echo "$WINDY_DEBIAN_SECURITY_MIRROR" | grep -Eq '^https?://[A-Za-z0-9./:_-]+$'; \
+    sed -i -e "s|^URIs: http://deb.debian.org/debian$|URIs: $WINDY_DEBIAN_MIRROR|" \
+      -e "s|^URIs: http://deb.debian.org/debian-security$|URIs: $WINDY_DEBIAN_SECURITY_MIRROR|" \
+      /etc/apt/sources.list.d/debian.sources; \
+    timeout --kill-after=5s 300s apt-get update -o APT::Update::Error-Mode=any \
+      -o Acquire::http::Timeout=30 -o Acquire::https::Timeout=30 -o Acquire::Retries=2; \
+    timeout --kill-after=5s 600s apt-get install --no-install-recommends --yes libseccomp2 util-linux git ca-certificates; \
+    rm -rf /var/lib/apt/lists/*
+RUN --mount=type=bind,from=fonts,source=/,target=/font-source \
+    echo '4a2515eb6db3978b897fef9709ed0d2b1f4c6c4df4d83d6c4ef65f71f1b1f502  /font-source/fonts.deb' | sha256sum -c - && \
+    dpkg -i /font-source/fonts.deb
+COPY --from=node /usr/local/bin/node /usr/local/bin/node
+COPY --from=dependencies /app/node_modules /app/node_modules
+COPY --from=build /app/apps/agent-server/dist ./dist
+COPY apps/agent-server/package.json ./package.json
+COPY apps/agent-server/plugins ./plugins
+COPY --chown=0:0 apps/agent-server/project ./project
+RUN chmod -R a+rX,a-w ./project
+RUN chmod 0444 ./plugins/subprocess.mjs ./plugins/confine-network.py
+COPY deploy/dsh/documents/requirements.lock /opt/windy-documents/requirements.lock
+COPY apps/agent-server/documents /opt/windy-documents
+RUN --mount=type=bind,from=document-wheels,source=/wheels,target=/wheels python -m venv /opt/venv && \
+    /opt/venv/bin/pip install --no-index --find-links=/wheels --require-hashes --only-binary=:all: -r /opt/windy-documents/requirements.lock && \
+    mkdir -p /app/data/agent/dsh && chmod 0711 /app/data/agent /app/data/agent/dsh
+ENV NODE_ENV=production PATH=/opt/venv/bin:/usr/local/bin:/usr/bin:/bin \
+    PYTHONDONTWRITEBYTECODE=1 PYTHONUTF8=1 PIP_NO_INDEX=1 \
+    AGENT_RUNTIME_DATABASE_PATH=/app/data/agent/embedded-dsh.sqlite AGENT_DSH_HOME=/app/data/agent/dsh
 EXPOSE 8080
-RUN mkdir -p /app/data/agent \
-  && chown -R windy:windy /app/data
-USER windy
-HEALTHCHECK --interval=15s --timeout=5s --start-period=10s --retries=4 \
-  CMD ["python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=3)"]
-CMD ["uvicorn", "southwind_agent_server.asgi:app", "--host", "0.0.0.0", "--port", "8080"]
+# Coordinator changes UID/GID for isolated workers; workers never run as root.
+HEALTHCHECK --interval=15s --timeout=5s --start-period=15s --retries=4 \
+    CMD ["node", "-e", "fetch('http://127.0.0.1:8080/health/ready',{signal:AbortSignal.timeout(3000)}).then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+CMD ["node", "dist/main.js"]

package/template/apps/agent-server/README.md

@@ -1,90 +1,52 @@
-# Windy Agent Server
-
-Python 3.12 Agent 运行时。HTTP 层只公开 Windy canonical Agent 契约；真实业务 Run 由
-`OpenAiCompatibleEngineAdapter` 直接执行，模型调用复用受治理的 OpenAI-compatible
-`/chat/completions` Provider。Engine、Provider 和 Tool 私有类型不会越过
-`AgentEngineAdapter`。
-
-```bash
-uv sync --frozen
-uv run pytest
-uv run ruff check .
-uv run ruff format --check .
-uv run mypy
-```
+# Agent Server：内置 DSH
+
+官方 npm DSH 固定 `0.2.1-rc.2`、Cordis `4.0.5`，随 Bun workspace 安装，Node 24.7+ 执行。Python 仅用于镜像内固定文档工具。
 
-HTTP 接口：
-
-- `GET /api/agent/runtime/compatibility`（内部认证、V1 协议 Offer）
-- `POST /api/agent/runs`
-- `GET /api/agent/runs/:runId/events`
-- `GET /api/agent/runs/:runId/result`
-- `POST /api/agent/runs/:runId/cancel`
-
-Run 创建使用 `Idempotency-Key`。事件以 SSE 传输，支持 `Last-Event-ID` 和 `after`
-断线重放，并周期发送 comment heartbeat。Provider 或 Engine 异常只映射为 canonical
-安全错误，不把原始异常正文暴露给调用方。
-
-兼容 Offer 返回 Engine identity、支持的协议版本、传输能力、callback auth profile 及三层摘要。
-新 Windy Server 会在 Run 请求头固定所选版本和 Offer digest；新 Agent Server 仍接受完全不带 pin
-的旧调用方，但拒绝半套或不匹配 pin。它只用于同一受控部署，不能把内部 token 发给外部业务系统。
-跨系统限制见 [Remote Agent Runtime 兼容契约](../../docs/architecture/agent-runtime-compatibility.md)。
-
-配置以下仅服务端可见的环境变量后启用 Direct Engine：
-
-```bash
-export AGENT_SERVER_INTERNAL_TOKEN='<random-token>'
-export QWEN_API_URL='https://dashscope-intl.aliyuncs.com/compatible-mode/v1'
-export QWEN_API_KEY='<server-secret>'
-export QWEN_MODEL='qwen-plus'
-export AI_PROVIDER_HTTPS_HOST_ALLOWLIST='dashscope-intl.aliyuncs.com'
-export AI_PROVIDER_CAPABILITIES='text-generation'
-export AI_PROVIDER_INPUT_MODALITIES='text'
-export AGENT_RUN_STORE_PATH='.data/agent-runs.sqlite3'
-export AI_PROVIDER_AUDIT_STORE_PATH='.data/provider-audit.sqlite3'
-export AI_PROVIDER_AUDIT_RETENTION_DAYS='90'
-uv run uvicorn southwind_agent_server.asgi:app
+```sh
+bun install --frozen-lockfile
+bun run --cwd apps/agent-server build
+bun run --cwd apps/agent-server start
 ```
 
-公网 URL 必须使用 HTTPS 且 Host 精确命中 allowlist；本机、容器服务名和内网地址允许
-HTTP。Provider 请求有连接与总超时、响应大小限制、错误脱敏和出网审计。缺少 URL、
-Key 或 Model 时使用 `UnavailableEngineAdapter` 稳定返回 unavailable，不调用模型。
-
-Direct Engine 保留文本、结构化输出、Citation、Vision Artifact、受治理 Tool、多轮 Tool、
-审批等待/恢复、取消、Usage 和 Provider Attempt。Tool 只接受 Operation 允许的 Key，执行时
-回调 Windy Tool Host 并携带当前 Run 的 opaque Execution Grant。Service 在每次模型轮次
-和 Tool 前后重新检查取消，避免取消后继续产生副作用或发布成功终态。
-
-VLM Operation readiness 比 Endpoint 可达性更严格。必须固定 Deployment 事实并声明图片
-offer；否则 `/health/vlm-ready` 返回 V1 `unavailable` snapshot，视觉 Operation 保持关闭：
-
-```bash
-export AI_PROVIDER_CAPABILITIES='text-generation,vision'
-export AI_PROVIDER_INPUT_MODALITIES='text,image'
-export AI_PROVIDER_DEPLOYMENT_IDENTITY='windy-deployment-v1_<uuid-v4>'
-export AI_PROVIDER_RELEASE_DIGEST='sha256:<64-lowercase-hex>'
-export AI_PROVIDER_READINESS_TTL_SECONDS='60'
-export AI_PROVIDER_MAX_CONCURRENT_RUNS='1'
-export AI_PROVIDER_MAX_QUEUE_DEPTH='0'
+产品登录后的同源 `/agent` 使用上游原生工作台。Windy Server 负责 Feature、License、RBAC、当前登录与业务工具授权；协调器保管 Provider 和内部凭据，用户 worker 仅持有可撤销的边界 token。Run、SSE、幂等、取消、Client Agent Session、Context、Artifact、审计和结果加密维持原公开协议。
+
+Linux 协调器按账号创建独立 UID、0700 HOME 与 workspace。默认最多两个 worker；每用户 heap 768 MiB、进程 128、文件描述符 512、单文件 128 MiB、HOME 软配额 512 MiB。子进程使用 Landlock 和 seccomp，能力缺失拒绝执行。全局模型容量至少预留一个槽位给 canonical/Client 调用，原生排队与父子任务共享预算；这些保护上限不代表硬件容量承诺。
+
+`AGENT_DSH_USER_EXTENSIONS` 默认开启；设为 `0` 关闭个人管理入口与个人技能发现，但不会卸载既有插件。用户安装的插件是其授权的可信代码，可访问本人的 HOME、会话和网络。撤销应先停用或卸载，再关闭入口。
+
+## 项目接入
+
+`project/host.ts` 是项目自有组合入口，使用 `DshHostConfiguration` 提供助手名称、业务说明、只读技能目录与额外公开 DSH 插件。Windy 不包含案件、笔录、产品 Copilot 历史或领域预设。项目插件只能调用受治理 Host 接口，不能通过工作区元数据授予权限。
+
+项目插件与技能资源放在 `project/` 下，例如 `project/plugins/business.mjs` 和 `project/skills/review/`；在 `host.ts` 中填写相对 Agent Server 的路径。整个目录随生产镜像交付，属于 root、对 Worker 只读，升级保留项目自有内容。该目录不承载 Provider 凭据或其它 Secret。
+
+品牌客户端读取当前平台 `/api/platform/branding` 的 `softwareName`、`logoUrl`、`description`，默认 Windy。中文、主题和 UI 使用公开 locale、theme、slots 与插件生命周期。
+
+共享技能通过官方 `ctx.skills.registerProvider` 接入；每次发现与读取都向产品 Server 重做当前授权。协调器将已授权的版本及附件物化为 HOME 外的 root-owned、用户组只读目录，版本变化后撤下旧目录。个人 `.dsh/skills` 仍由原生技能管理负责。
+
+## 存储与交付
+
+canonical 数据库使用 `AGENT_RUNTIME_DATABASE_PATH`（默认 `/app/data/agent/embedded-dsh.sqlite`），用户数据使用 `AGENT_DSH_HOME`（默认 `/app/data/agent/dsh`）。当前仅支持单 Agent Server 副本。
+
+旧 Python Agent 专用数据库不读取、不迁移；切换前备份后使用新路径。业务 PostgreSQL、文件、AH-1 Session、Memory 和 Workflow 的治理义务继续保留。旧记录无法取得运行详情时明确标记缺失。Provider 原有配置继续使用；已退役 Python 的 OTEL exporter 和 connect-only timeout 不再声称受支持。
+
+Office 预览复用官方 office-to-pdf/PDF.js，Linux `libreoffice-kit-wasm@0.1.5` 及许可源码随镜像离线交付。每用户转换并发 1、后台 0、输入 16 MiB、输出 20 MiB、缓存 32 MiB/2 项、超时 60 秒。WASM RSS 不受 V8 heap 完整限制。
+
+## 聚焦验证入口
+
+```sh
+bun run --cwd apps/agent-server typecheck
+bun run --cwd apps/agent-server test
+bun test apps/agent-server/native apps/agent-server/plugins
+bun run --cwd apps/agent-server test:coordinator
+bun run --cwd apps/agent-server test:confinement
 ```
 
-Readiness 使用固定一像素合成图片调用已配置的 `/chat/completions` 并要求有界结构化结果。
-它不读取客户截图，也不把用户 Artifact、URL、Run ID、Prompt 或 Provider 输出放进 health
-payload。
-
-未设置 `AGENT_RUN_STORE_PATH` 时的 `InMemoryRunStore` 仅用于 deterministic 测试。
-配置路径后使用有界 SQLite Store，可在单副本重启后保留 Run/Event/Result 和 cursor；
-多副本部署必须使用共享 Store。Run 固定保存稳定 Engine ID
-`windy.direct.openai-compatible.v1`；历史 `google.adk.v2` Run 只读兼容，不回填，也不能由
-Direct Engine 从中断点继续。
-
-每次实际 Provider HTTP 调用前，Runtime 对 Manifest 允许的输入 JSON Pointer 与 outbound
-envelope 执行 DLP，并将 deployment、operation、run、attempt、分类集合、序列化字节数和
-allow/redact/reject 决策写入 append-only 审计。审计不保存 Prompt、请求正文或 Secret；
-审计写入失败时禁止出网。
-
-开发与运维统一使用 Windy 主站 `/admin/system/ai-runtime`。详情中的脱敏 Trajectory 展示
-Run、输入模态、Tool Key、审批、Usage、Artifact 数量、取消/失败和终态，不展示输入输出正文、
-Tool 参数、chain-of-thought 或 Provider 原始响应。业务历史会话通过
-`registerAgentSessionProviders()` 投影到受当前登录身份、Feature、RBAC 和对象范围保护的
-主站接口；不再存在独立调试站点、专用调试身份或第二种 Token。
+Node 契约使用真实 DSH Loop 与合成 Provider。Linux 镜像、真实认证模型、文档质量及现场负载分别验收；不得互相替代。镜像验证可用 `WINDY_AGENT_TEST_IMAGE` 指定已构建镜像。
+
+### 本机 JSON 输出兼容模式
+
+默认 `QWEN_STRUCTURED_OUTPUT_MODE=json_schema` 保持提供方严格结构输出。
+只有运行器无法编译合法业务 Schema 时，可在该部署显式设置 `json_object`。
+此模式仅改变无工具请求的 `response_format`：完整授权 Schema 仍进入系统提示，输出仍经过原有 JSON Schema 与业务校验；缺字段、类型错误和无效引用不会被补齐或放行。
+该配置不改变 Manifest、Host Guard、输出 Schema 授权或其它部署的默认值。

package/template/apps/agent-server/documents/office.py

@@ -0,0 +1,216 @@
+"""Bounded, local document helpers; no model calls, network, or business writes."""
+
+from datetime import date, datetime
+from decimal import Decimal, InvalidOperation
+from hashlib import sha256
+from io import BytesIO
+from pathlib import Path
+from zipfile import ZipFile
+
+from docx import Document
+from docx.oxml.ns import qn
+from docx.shared import Pt
+from docx.table import Table
+from openpyxl import Workbook, load_workbook
+from openpyxl.comments import Comment
+from pypdf import PdfReader
+
+MAX_INPUT_BYTES = 16 * 1024 * 1024
+# Upstream /api/file uses attachments.imageLimits.maxImageBytes (20 MiB by default).
+MAX_OUTPUT_BYTES = 20 * 1024 * 1024
+MAX_ROWS = 10_000
+
+
+def digest(path: Path) -> str:
+    return sha256(path.read_bytes()).hexdigest()
+
+
+def check_input(path: Path, zipped: bool = False) -> None:
+    if not path.is_file() or not 0 < path.stat().st_size <= MAX_INPUT_BYTES:
+        raise ValueError("input must be a nonempty file of at most 16 MiB")
+    if zipped:
+        with ZipFile(path) as archive:
+            entries = archive.infolist()
+            if len(entries) > 2048 or sum(e.file_size for e in entries) > 64 * 1024 * 1024:
+                raise ValueError("Office ZIP exceeds entry/expanded-size budget")
+            if any(e.file_size > MAX_INPUT_BYTES for e in entries):
+                raise ValueError("Office ZIP member exceeds 16 MiB")
+
+
+def save_new(document, output: Path) -> None:
+    """Exclusive creation preserves originals and previously generated revisions."""
+    content = BytesIO()
+    document.save(content)
+    data = content.getvalue()
+    if not 0 < len(data) <= MAX_OUTPUT_BYTES:
+        raise ValueError("output exceeds the 20 MiB native download budget")
+    with output.open("xb") as handle:
+        handle.write(data)
+
+
+def new_document(title: str):
+    document = Document()
+    normal = document.styles["Normal"]
+    normal.font.name = "Noto Sans CJK SC"
+    normal.font.size = Pt(11)
+    normal.element.rPr.rFonts.set(qn("w:eastAsia"), "Noto Sans CJK SC")
+    document.core_properties.title = title
+    document.core_properties.author = ""
+    document.core_properties.last_modified_by = ""
+    document.add_heading(title, 0)
+    return document
+
+
+def read_text(source: Path) -> str:
+    suffix = source.suffix.lower()
+    check_input(source, zipped=suffix == ".docx")
+    if suffix == ".docx":
+        document = Document(source)
+        lines = []
+        for block in document.iter_inner_content():
+            if isinstance(block, Table):
+                lines.extend(" | ".join(cell.text for cell in row.cells) for row in block.rows)
+            else:
+                lines.append(block.text)
+        text = "\n".join(lines)
+    elif suffix == ".pdf":
+        reader = PdfReader(source, strict=True)
+        if reader.is_encrypted or len(reader.pages) > 100:
+            raise ValueError("encrypted PDFs or PDFs over 100 pages are unsupported")
+        pages = [page.extract_text() or "" for page in reader.pages]
+        if any(not page.strip() for page in pages):
+            raise ValueError("PDF has a page without extractable text; OCR or page review is required")
+        text = "\n".join(pages)
+    else:
+        raise ValueError("only .docx and text-based .pdf are supported")
+    if not text.strip() or len(text) > 1_000_000:
+        raise ValueError("missing extractable text or extracted text exceeds budget")
+    return text
+
+
+def write_revision(source: Path, output: Path, text: str, title: str) -> None:
+    """Write a new editable text draft, without promising source layout fidelity."""
+    if output.suffix.lower() != ".docx":
+        raise ValueError("revision output must use .docx")
+    read_text(source)
+    if not text.strip() or len(text) > 1_000_000:
+        raise ValueError("revision text is empty or exceeds budget")
+    before = digest(source)
+    document = new_document(title)
+    document.core_properties.subject = f"Source SHA256: {before}"
+    for paragraph in text.splitlines():
+        document.add_paragraph(paragraph)
+    save_new(document, output)
+    if digest(source) != before:
+        raise RuntimeError("source changed during revision")
+
+
+def money(value) -> Decimal:
+    if isinstance(value, bool) or not isinstance(value, (str, int, float, Decimal)):
+        raise ValueError("amount must be a finite decimal value")
+    try:
+        amount = Decimal(str(value))
+    except InvalidOperation as error:
+        raise ValueError("invalid decimal amount") from error
+    if not amount.is_finite() or abs(amount) >= Decimal("1e12"):
+        raise ValueError("amount is non-finite or outside budget")
+    if amount != amount.quantize(Decimal("0.01")):
+        raise ValueError("amount must have at most two decimal places")
+    return amount
+
+
+def summarize_excel(source: Path, output: Path, *, unit: str) -> Decimal:
+    """Known four-column sample contract; formulas/macros are deliberately rejected."""
+    if not isinstance(unit, str) or not unit.strip() or len(unit) > 32:
+        raise ValueError("an explicit amount unit is required; no automatic conversion")
+    if source.suffix.lower() != ".xlsx" or output.suffix.lower() != ".xlsx":
+        raise ValueError("only .xlsx is supported")
+    check_input(source, zipped=True)
+    before = digest(source)
+    workbook = load_workbook(source, read_only=True, data_only=False)
+    try:
+        if len(workbook.worksheets) != 1:
+            raise ValueError("sample summarizer requires exactly one worksheet")
+        sheet = workbook.active
+        if sheet.max_row is not None and sheet.max_row > MAX_ROWS + 1:
+            raise ValueError("worksheet exceeds row budget")
+        # XLSX dimension metadata can understate the data and silently truncate read_only iteration.
+        sheet.reset_dimensions()
+        rows = sheet.iter_rows()
+        header = next(rows, ())
+        if [cell.value for cell in header] != ["编号", "名称", "日期", "金额"]:
+            raise ValueError("expected columns: 编号, 名称, 日期, 金额")
+        result = Workbook()
+        target = result.active
+        target.title = "整理结果"
+        target.append(["编号", "名称", "日期", "金额"])
+        total = Decimal("0.00")
+        last_row = 1
+        for last_row, row in enumerate(rows, start=2):
+            if last_row > MAX_ROWS + 1 or len(row) != 4:
+                raise ValueError("actual worksheet data exceeds row/column contract")
+            if any(cell.data_type in ("f", "e") for cell in row):
+                raise ValueError("formula or error cells require a separately verified calculation")
+            identifier, label, when, value = (cell.value for cell in row)
+            if not isinstance(identifier, str) or not identifier.isdigit():
+                raise ValueError("identifiers must be text so leading zeros remain exact")
+            if not isinstance(label, str) or not isinstance(when, (date, datetime)):
+                raise ValueError("name/date column types do not match contract")
+            amount = money(value)
+            total += amount
+            target.append([identifier, label, when, format(amount, ".2f")])
+            # append() infers formulas from '=' even when the source cell was literal text.
+            for column in (1, 2, 4):
+                target.cell(target.max_row, column).data_type = "s"
+            target.cell(target.max_row, 1).number_format = "@"
+            target.cell(target.max_row, 3).number_format = "yyyy-mm-dd"
+        target.append(["汇总", "", None, format(total, ".2f")])
+        # Currency stays decimal text: no binary-float coercion or cached formula claim.
+        target.column_dimensions["A"].width = 16
+        target.column_dimensions["B"].width = 24
+        target.column_dimensions["C"].width = 16
+        target.column_dimensions["D"].width = 20
+        source_range = f"{sheet.title}!A1:D{last_row}"
+        target["D1"].comment = Comment(f"金额单位：{unit}；未转换单位。来源：{source_range}。", "DSH")
+        provenance = result.create_sheet("来源说明")
+        for label, value in (("来源文件", source.name), ("来源 SHA256", before),
+                             ("来源范围", source_range), ("筛选条件", "全部输入数据行，无过滤"),
+                             ("金额单位", unit), ("单位转换", "未转换"),
+                             ("数据行数", str(last_row - 1)), ("Decimal 合计", format(total, ".2f"))):
+            provenance.append([label, value])
+            provenance.cell(provenance.max_row, 2).data_type = "s"
+        provenance.column_dimensions["A"].width = 18
+        provenance.column_dimensions["B"].width = 72
+        save_new(result, output)
+    finally:
+        workbook.close()
+    if digest(source) != before:
+        raise RuntimeError("source changed during summary")
+    return total
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(description=__doc__)
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    read_parser = subparsers.add_parser("read")
+    read_parser.add_argument("source", type=Path)
+    revise_parser = subparsers.add_parser("revise")
+    revise_parser.add_argument("source", type=Path)
+    revise_parser.add_argument("output", type=Path)
+    revise_parser.add_argument("--text", type=Path, required=True)
+    revise_parser.add_argument("--title", default="文档修订稿")
+    excel_parser = subparsers.add_parser("summarize-excel")
+    excel_parser.add_argument("source", type=Path)
+    excel_parser.add_argument("output", type=Path)
+    excel_parser.add_argument("--unit", required=True, help="source amount unit, e.g. 元; no conversion")
+    arguments = parser.parse_args()
+    if arguments.command == "read":
+        print(read_text(arguments.source))
+    elif arguments.command == "revise":
+        check_input(arguments.text)
+        write_revision(arguments.source, arguments.output,
+                       arguments.text.read_text(encoding="utf-8"), arguments.title)
+    else:
+        print(format(summarize_excel(arguments.source, arguments.output, unit=arguments.unit), ".2f"))

package/template/apps/agent-server/documents/query_report.py

@@ -0,0 +1,136 @@
+"""Build a source-attributed DOCX from a complete, normalized MCP query export.
+
+This checks a local export's declared coverage, not its authenticity or authorization.
+The MCP caller must fetch/re-authorize every page and normalize the actual tool response.
+"""
+
+import argparse
+import json
+from datetime import datetime
+from decimal import Decimal
+from hashlib import sha256
+from pathlib import Path
+
+from office import MAX_ROWS, check_input, money, new_document, save_new
+
+
+def required_text(value, field: str, limit: int = 2048) -> str:
+    if not isinstance(value, str) or not value.strip() or len(value) > limit:
+        raise ValueError(f"invalid {field}")
+    return value
+
+
+def validate_snapshot(snapshot: dict) -> tuple[dict, list[dict], Decimal]:
+    if (not isinstance(snapshot, dict) or type(snapshot.get("schemaVersion")) is not int
+            or snapshot["schemaVersion"] != 1):
+        raise ValueError("unsupported snapshot schema")
+    if snapshot.get("complete") is not True or snapshot.get("errors") != []:
+        raise ValueError("incomplete or partially failed query export")
+    if snapshot.get("partial", False) is not False or snapshot.get("truncated", False) is not False:
+        raise ValueError("query export declares partial or truncated coverage")
+    source = snapshot.get("source")
+    if not isinstance(source, dict) or source.get("kind") not in (
+        "synthetic-fixture", "mcp-query-export"
+    ):
+        raise ValueError("missing explicit source kind")
+    for key in ("tool", "queryId", "scope", "query", "capturedAt"):
+        required_text(source.get(key), f"source.{key}")
+    required_text(source.get("unit"), "source.unit", limit=32)
+    if "metric" in source:
+        required_text(source["metric"], "source.metric", limit=64)
+    captured_at = datetime.fromisoformat(source["capturedAt"].replace("Z", "+00:00"))
+    if captured_at.tzinfo is None:
+        raise ValueError("capturedAt must include timezone")
+    total = snapshot.get("total")
+    if type(total) is not int or not 0 <= total <= MAX_ROWS:
+        raise ValueError("missing total or total exceeds row budget")
+    pages = snapshot.get("pages")
+    if not isinstance(pages, list) or not 1 <= len(pages) <= 100:
+        raise ValueError("missing pages or page budget exceeded")
+    records, identifiers, visited = [], set(), set()
+    expected_cursor, amount = None, Decimal("0.00")
+    for index, page in enumerate(pages):
+        if not isinstance(page, dict) or page.get("status") != "success":
+            raise ValueError("query page failed")
+        if page.get("truncated") is not False or page.get("partial", False) is not False:
+            raise ValueError("truncated or partial query page")
+        if page.get("errors", []) != []:
+            raise ValueError("query page contains errors")
+        if "cursor" not in page or "nextCursor" not in page:
+            raise ValueError("pagination cursors must be explicit")
+        cursor, following = page["cursor"], page["nextCursor"]
+        if cursor != expected_cursor:
+            raise ValueError("missing or out-of-order query page")
+        if following is not None:
+            required_text(following, "nextCursor")
+            if following in visited:
+                raise ValueError("repeated pagination cursor")
+            visited.add(following)
+        if (index == len(pages) - 1) != (following is None):
+            raise ValueError("pagination must terminate exactly on the final page")
+        expected_cursor = following
+        items = page.get("records")
+        if not isinstance(items, list) or len(records) + len(items) > MAX_ROWS:
+            raise ValueError("invalid records or row budget exceeded")
+        for item in items:
+            if not isinstance(item, dict):
+                raise ValueError("invalid record")
+            identifier = required_text(item.get("id"), "record.id")
+            required_text(item.get("label"), "record.label")
+            required_text(item.get("sourceRef"), "record.sourceRef")
+            if "unit" in item and item["unit"] != source["unit"]:
+                raise ValueError("mixed record units require explicit normalization before reporting")
+            if identifier in identifiers:
+                raise ValueError("duplicate record across query pages")
+            identifiers.add(identifier)
+            # Exporters must preserve decimal strings, rather than JSON floating point.
+            required_text(item.get("amount"), "record.amount", limit=32)
+            amount += money(item["amount"])
+            records.append(item)
+    if len(records) != total:
+        raise ValueError("record count differs from declared total")
+    return source, records, amount
+
+
+def generate_report(source_path: Path, output: Path) -> dict:
+    if output.suffix.lower() != ".docx":
+        raise ValueError("report output must use .docx")
+    check_input(source_path)
+    payload = source_path.read_bytes()
+    source_digest = sha256(payload).hexdigest()
+    snapshot = json.loads(payload)
+    source, records, total = validate_snapshot(snapshot)
+    metric = source.get("metric", "金额")
+    document = new_document("查询数据汇总报告")
+    if source["kind"] == "synthetic-fixture":
+        document.add_paragraph("脱敏合成样例，仅用于文件和来源覆盖检查。")
+    document.add_paragraph(f"导出时声明的查询范围：{source['scope']}")
+    document.add_paragraph(f"查询条件：{source['query']}")
+    document.add_paragraph(f"在该范围内完成 {len(snapshot['pages'])} 页，共 {len(records)} 条记录。")
+    document.add_paragraph(f"{metric}合计：{format(total, '.2f')} {source['unit']}（Decimal 计算）。")
+    table = document.add_table(rows=1, cols=4)
+    table.style = "Light Shading Accent 1"
+    for cell, label in zip(table.rows[0].cells, ("记录 ID", "名称", f"{metric}（{source['unit']}）", "来源定位")):
+        cell.text = label
+    for record in records:
+        values = (record["id"], record["label"], format(money(record["amount"]), ".2f"),
+                  record["sourceRef"])
+        for cell, value in zip(table.add_row().cells, values):
+            cell.text = value
+    document.add_heading("来源与覆盖边界", level=1)
+    for label, value in (("MCP 工具", source["tool"]), ("查询关联", source["queryId"]),
+                         ("导出时间", source["capturedAt"]), ("快照 SHA256", source_digest)):
+        document.add_paragraph(f"{label}：{value}")
+    document.add_paragraph("来源定位用于回查；访问来源仍按当前身份和数据范围重新授权。")
+    document.add_paragraph("报告反映该导出时点和筛选范围，不代表其他范围或实时数据库全量。")
+    save_new(document, output)
+    return {"records": len(records), "total": format(total, ".2f"), "unit": source["unit"], "metric": metric,
+            "sourceSha256": source_digest, "sourceKind": source["kind"]}
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("snapshot", type=Path)
+    parser.add_argument("output", type=Path)
+    arguments = parser.parse_args()
+    print(json.dumps(generate_report(arguments.snapshot, arguments.output), ensure_ascii=False))