| name | cw-xlsx-to-wiki |
| description | 当用户提供或提及 `.xlsx` 工作簿，并需要将其导入可编辑的 wiki workspace、按 sheet 或 region 检查结构与数据、基于 workspace 进行分析或修改后校验一致性，或从已校验的 workspace 重建新的 `.xlsx` 文件时使用。通过 import、inspect、check、reimport 和 build 工作流处理；不用于非 `.xlsx` 文件、直接编辑 OOXML，或把派生输出作为新的编辑源。 |
| version | 1.0.1 |
XLSX To Wiki
这个 skill 按 SKILL.md + scripts/ + references/ 结构组织，适合接入 CreatorWeave 的按需加载模型。
不要从当前工作目录、项目目录结构或文档路径推导 skill 根路径。脚本路径与资源路径应以运行时提供的信息、read_skill 返回内容或 skill loader 注入结果为准。
适用范围
适用场景：
- 将一个
.xlsx 文件导入为 wiki workspace 结构
- 校验导入后 workspace 是否完整、可重建
- 基于导入后 workspace 继续做分析探索、问题发现和洞察整理
- 基于导入后 workspace 生成新的
.xlsx 输出文件
- 以 sheet / region 视角检查工作簿内容
不适用场景：
- 输入不是
.xlsx 工作簿
- 用户只想讨论概念，不需要实际导入、检查、重建
- 用户要求直接编辑
.xlsx 内的 OOXML
核心规则
- 使用这个 skill 时，优先通过
read_skill 读取入口说明，再按需读取 references/ 或 scripts/ 资源
- 始终通过
scripts/run_workbook_tool.py 或其导出函数处理正式导入、检查、查看和构建任务
- 不要跳过
check 直接 build
- 不要在
check 失败后执行 build
- 每次工具调用都先检查返回值中的
ok；失败后停止当前流程并处理 error_code
- 原始
xlsx 文件默认只作为 import 输入，不直接作为编辑对象
- 执行
import 后，后续修改默认聚焦于 workspace_path 及其中产物
- 如果检测到原始
xlsx 在 import 后发生变化，必须先执行 reimport
outputs/ 下的重建产物是派生文件，不能作为新的真值来源- 如果用户目标是分析、提问或写报告，优先基于已同步的 wiki workspace 继续探索，而不是反复回到原始
xlsx
- 转成 wiki 产物时，写文件逻辑必须保持流式写入
- wiki workspace 中生成的文件和目录必须使用小写英文命名；源工作簿和 sheet 的原始语言仅保留在展示标题与元数据中
- 新增
import 或依赖前，先评估会引入多少额外文件，避免 Pyodide 中的文件数和内存暴涨
标准流程
- 识别输入
.xlsx
- 执行
import
- 按需执行
inspect
- 按需修改 workspace 产物
- 执行
check
- 如果源文件已变化，停止后续流程并执行
reimport
reimport 成功后，重新执行必要的 inspect、修改和 check- 仅在
check 成功后执行 build
如果用户目标是“分析这个 workbook / 给我一份洞察报告”，默认在 import 或 check 之后切到分析与报告模式，而不是额外切换到第二个独立 skill。
分析与报告模式
当用户目标是下面这些任务时，继续在当前 skill 内完成：
- 发现值得负责人关注的问题
- 基于 wiki workspace 做证据探索
- 组织管理导向的洞察报告
- 输出 HTML 或文本形式的分析结果
这部分工作的核心不是重新解析 .xlsx，而是复用前面已经导入好的 wiki workspace，并围绕证据做：
- 扩大证据覆盖
- 识别客观信号
- 选择高价值问题
- 区分事实、假设和待验证事项
- 组织最终报告
默认不要求额外依赖分析脚本；优先基于 workspace 内容和按需加载的 references 完成分析。
先读哪些参考
- 工作流与前置条件：
references/workflow.md
- workspace 目录与产物职责：
references/workspace-layout.md
- 修改规则与定位方法：
references/editing-rules.md
- 返回 schema、错误码与 guard：
references/contracts.md
- Pyodide 约束与运行方式：
references/runtime-constraints.md
- 内置 skill 接入注意事项：
references/creatorweave-builtin.md
如果用户目标是分析 / 洞察 / 报告，再继续读取：
- 问题选择标准：
references/question-framework.md
- 洞察推理边界：
references/insight-reasoning.md
- 报告受众导向：
references/report-audience.md
- 报告结构模板：
references/report-template.md
- 常见信号类型：
references/signal-types.md
环境准备
Pyodide 默认可能不带 pyyaml。优先复用运行时已安装的依赖；确认缺失并且确实需要时再安装一次。脚本目录不要自行猜测，优先使用运行时提供的 Python execution path；在 CreatorWeave 内置 skill 场景下，通常会挂载到 /mnt_skills/builtin/<skill-name>/scripts/。
对 builtin skill，推荐直接使用：
- script import path:
/mnt_skills/builtin/cw-xlsx-to-wiki/scripts
- source xlsx path: 优先使用
/mnt/... 或 /mnt_assets/... 下实际存在的文件
- 不要把浏览器静态资源 URL（如
/assets/foo.xlsx）当作 Pyodide 文件路径传给 source_path
import sys
from pathlib import Path
skill_scripts = Path("<runtime-provided-scripts-path>").resolve()
if not skill_scripts.exists():
raise FileNotFoundError(f"Skill scripts directory does not exist: {skill_scripts}")
if str(skill_scripts) not in sys.path:
sys.path.insert(0, str(skill_scripts))
from run_workbook_tool import check_wiki, inspect_sheet, reimport_source_xlsx, wiki_to_xlsx, xlsx_to_wiki
最短示例
import_payload = xlsx_to_wiki(
source_path="/mnt/path/to/input.xlsx",
job_id="job_001",
workspace_root="/mnt_assets/xlsx2wiki_workspace",
preview_rows=10,
display_name="Workbook Import",
import_mode="full",
)
if not import_payload["ok"]:
raise RuntimeError(import_payload["error_code"])
check_payload = check_wiki(
workspace_path=import_payload["workspace_path"],
fail_on_warning=False,
)
if not check_payload["ok"]:
raise RuntimeError(check_payload["error_code"])
build_payload = wiki_to_xlsx(
workspace_path=import_payload["workspace_path"],
output_filename="rebuilt.xlsx",
overwrite=True,
)
if not build_payload["ok"]:
raise RuntimeError(build_payload["error_code"])
如果 check 或 build 返回 SOURCE_XLSX_MODIFIED，必须改走：
reimport_payload = reimport_source_xlsx(
workspace_path=import_payload["workspace_path"],
)
if not reimport_payload["ok"]:
raise RuntimeError(reimport_payload["error_code"])
reimport 成功后，必须重新执行 check；只有新的 check_payload["ok"] 为 True 时才允许 build。
Use import_mode="full" unless you explicitly need debug-only artifacts.
