#JoySpace 文档与协同

JoySpace 文档与协同操作技能的统一入口（joyme_joyspace）。单入口、强约束、低噪执行，优先保证可创建、可读取、可校验、可复用。

#触发条件

用户意图涉及 JoySpace 文档或协同操作，例如：

• 创建：新建文档、表格、多维表、PPT、白板、会议文档
• 读取：查看/读取/总结文档、读取评论、抽取白板/流程图/设计稿
• 编辑：修改/填写/替换已有文档内容
• 搜索：按团队/目录搜索、相似方案检索、收到的文档
• 协同：发送文档或文件给联系人
• TRD：按 PRD 生成技术文档

#设计目标

• 单入口、强约束、低噪执行
• 优先保证「可创建、可读取、可校验、可复用」
• 规则去重，避免同类场景多套说法冲突

#运行环境

#调用入口

所有 JoySpace 能力必须通过 action 字段分发，参数形态与 joyme_joyspace MCP 工具一致。

脚本入口（平台无关，任意 cwd 均成立）：

bash "<skill 根>/scripts/joyspace.sh" '<json>'

首次或缺失依赖时先执行：node "<skill 根>/scripts/ensure-deps.mjs"

备选（MCP）：Cursor 已配置 MCP 时，可直接调用 joyme_joyspace 工具；与脚本入口二选一，勿重复调用。

skill 根目录 = skills/joyspace-official-full（即本 SKILL.md 所在目录）。不要使用绑定特定宿主的相对路径（如 .cursor/skills/...）。

#登录态

• 位置：<skill 根>/.joyspace-auth/
• 来源：仅可由本 skill 的 HiOffice 三步认证（京 Me 桌面客户端）或 Playwright 浏览器登录生成
• 登录失效：HiOffice 路径就地刷新 token 并重试；Playwright 路径写入新 cookie 后由宿主重启 MCP；脚本场景 exit code 2 表示需刷新后重跑

#全局行为约束

• 涉及创建时，必须先确认保存位置（team_id、folder_id 至少一个有效）
• 默认不猜测地址；参数冲突先向用户确认
• 评审区 / checklist 禁填时必须留空
• 不确定内容必须留空，禁止「待补充 / 待确认」
• 默认低噪输出：仅「结论、证据、下一步」
• 禁止使用 fill_doc_routing：对已有文档的内容写入请改用 fill_doc_via_slate（0.2.5+）

#地址解析

#解析优先级

1. 用户明确给出的结构化参数
2. JoySpace 链接解析结果
3. 预设映射

#链接规则

#私人空间

仅当用户明确说「我的 / 个人 / 私人空间」时，才允许 team_id=root, folder_id=root。

#路由决策

#创建意图

命中「创建 / 新建 / 生成 + 文档 / 表格 / 多维表 / PPT / 白板 / 会议文档」：

• 必走 create_doc_routing
• 未确认位置不得创建

#文档读取 / 总结

命中「查看 / 读取 / 总结文档」：

1. 先 get_page_basic_info
2. 再按类型分流（普通文档 → get_normal_json_content，表格 / 多维表走对应 action）
3. 若 get_normal_json_content 返回 data._unread_embeds 数组，必须按数组逐项调对应的 extract_action，把每条结果纳入总结
4. _unread_embeds 项默认全部都要调（must_call: true），仅当用户明确说「不用看里面的设计稿 / 白板」才可省略

评论读取：命中「读取 / 查看评论」→ 直接 list_comments（page_id 必填），无需先 get_page_basic_info。

内嵌内容抽取：

#搜索类

#协同发送

发给联系人：search_employee →（本地文件先上传）→ send_to_contact

本地文件 + 发送场景：优先文件上传链路，不先创建文档。

#克隆模版与结构化填空

适用于复制已有模版页的 Slate 结构，再按模版语义填空。不是 TRD 标准链路里的「整包正文 JSON 一次新建」。

• content 应为：多行「键: 值」结构化文本，可附带 Mermaid 源码块
• content 禁止：勿把 get_normal_json_content 导出的整包正文 JSON 当成 content 传入

#编辑已有文档（fill_doc_via_slate，0.2.5+）

命中「修改 / 编辑 / 填写 / 替换 / 插入 + 已有文档」：

1. 先 get_normal_json_content 拿节点结构 + id
2. 对每个要修改的位置选叶子级安全节点 id
3. 调 fill_doc_via_slate，传 edits[]：

可选 color（0.2.9+）：写红色等带色文字，取值如 "red" / "#F5222D" / rgb(...)。

4. 调 get_normal_json_content 回读校验

硬约束：

• void 节点（docfile / img / text-draw）不能 set-paragraph，但 insert-image placement=replace 可整体替换
• 富文本格式在 set-paragraph 后会丢失
• 不要重叠编辑父子节点
• set-paragraph + color 会重建节点 → 该节点 id 变化，同批 edits 里勿混用旧 id

#删除文档（delete_doc_routing，0.2.6+）

不可逆操作，默认禁止 LLM 自主调用：

1. 先 get_page_basic_info 拿到文档标题 + 团队 + 文件夹
2. 向用户回显标题并询问确认
3. 调 delete_doc_routing，必须带 confirm: true
4. 返回中检查 verified === true

#TRD 专用模块（最高优先）

#触发特征

用户明确要求「写 TRD / 生成 TRD / 交付 TRD / 按 PRD 出技术文档」。

#固定单路径

1. get_normal_json_content(模板)
2. 按字段映射在 JSON 中原位填写内容，一次性调用 create_doc_routing 创建文档（不传 source_page_id）
3. get_normal_json_content(新文档回读校验)

#JSON 填空规则

• 先解析模板结构（标题、表格行列头、diagram / text-draw）
• 按字段映射原位填空：命中才填，不确定留空
• 表格按行头 / 列头落位，不得错位
• 流程图必须是 flowchart TD，落在「2.1、方案流程图」
• 禁止 markdown 覆盖式写入替代 JSON 填空

#禁填规则

• 2.2、方案评审记录 默认留空
• 任意 checklist / 上线检查 / 验收 check 区域默认留空

#回读校验

至少校验：正文非空、关键字段可回读、流程图可回读。若返回 alignment_check，必须输出 matched/total/allMatched + 未命中字段清单。

#常用执行模板

#位置缺失追问

需要先确认保存位置后才能创建:
1. 回复"保存到私人空间"
2. 发送一个空间/文件夹地址(知识库名称、目录名称或 JoySpace 链接)
3. 提供 2-5 个关键词,我帮你搜索可用位置

#TRD 完成回报

已完成 TRD 创建并回读校验:
- 链接:<joyspace-url>
- 校验:matched=<m> / total=<t> / allMatched=<bool>
- 未命中项:<list>
- 说明:评审区/checklist 保持空白,不确定项保持空白

#错误与降级策略

• 地址冲突：暂停执行，先确认地址
• 权限不足：返回失败原因 + 需要补充的权限 / 位置信息
• 内容解析失败：返回证据并请求补充信息或改用可读源
• 创建失败：优先重试一次同 action；仍失败再给出最小必要人工确认项

#文件导航