claw-deck

ClawDeck — 工作区管理器

Agent 的项目外部大脑。激活后，Agent 会持续将任务、成果和知识同步到对应的 LiveDoc，让任何人（包括未来的会话或同事）都能加载工作区并立即获得完整上下文。

核心概念

概念	描述
工作区	一个项目 = 一个 LiveDoc
活动工作区	会话级状态；所有操作都会自动同步到此处
README	Agent 对项目的记忆；由 Agent 主动维护
成果	关键输出；保存前 Agent 会先询问
任务	实质性工作的跟踪记录；由 Agent 静默维护
注册表	~/.claude/workspaces.json，将项目名称映射到 LiveDoc ID

注册表格式：

{
  "workspaces": {
    "client-acme": "abc123",
    "project-x": "def456"
  }
}

脚本简写

在以下所有命令中，$SCRIPT 指：

node felo-livedoc/scripts/run_livedoc.mjs

不适用场景

• 简单闲聊或澄清问题
• 与任何项目或工作区无关的一次性生成
• 用户尚未安装 Felo LiveDoc NPM 包

---

工作流

0. 首次安装

用户粘贴 GitHub 安装链接 → 执行安装 → 完成后，自动进入登录流程（0a）。

0a. 登录 / 重新授权

触发条件（满足其中一项）：

• 首次安装，尚未配置 Key
• 任何 API 调用返回 {"status":401,"code":"UNAUTHORIZED","message":"Invalid API Key"}

流程：

1. 发送登录链接：

   "请点击链接登录 / 注册 Felo 账户：https://felo.ai/settings/api-keys 完成后，请将 Key 粘贴给我，我会自动完成设置。"

2. 用户粘贴 Key → 写入配置：

   export FELO_API_KEY="user's Key"
   

   或保存到 ~/.claude/env（取决于平台）。
3. 验证：$SCRIPT list
   • 成功 + 首次安装 → 显示使用介绍（见下方“首次使用介绍”）
   • 成功 + 重新授权 → “✅ 授权已更新。” → 重试失败的命令
   • 失败 → “Key 无效，请重新粘贴。”

首次使用介绍（仅在首次安装时显示；重新授权时跳过）：

"🎉 设置完成！现在可以使用以下命令管理工作区：

📁 创建工作区 — 为新项目创建独立工作区 示例：“创建一个名为 Client Acme 的工作区”

📂 加载工作区 — 打开现有项目，恢复上下文 示例：“加载 Acme 工作区”

📋 查看工作区 — 列出所有项目或查看项目内容 示例：“我有哪些工作区？” / “Acme 工作区里有什么？”

💾 保存成果 — 重要输出会提示你保存

工作区会记录我们所做的一切。你可以随时在网页上查看：https://felo.ai"

1. 加载工作区

1. 读取 ~/.claude/workspaces.json，模糊匹配项目名称。如果本地未找到，则尝试 $SCRIPT list --keyword。
2. **找到：**设为活动工作区 → $SCRIPT get-readme SHORT_ID → 将 README 作为工作区简介展示 → 追加链接 https://felo.ai/livedoc/SHORT_ID?from=claw。如果 README 为空或缺失，则改用 $SCRIPT resources SHORT_ID 显示资源列表。
3. 未找到：“未找到与‘[X]’对应的工作区。要我创建一个吗？”

2. 创建工作区

$SCRIPT create --name "Project Name" --description "workspace"

提取 short_id → 初始化 README（见下方“README 结构模板”）→ 更新注册表 → 设为活动工作区 → 回复：

“✅ 工作区‘[X]’已创建。📎 https://felo.ai/livedoc/SHORT_ID?from=claw”

3. 任务同步（强制）

铁律：工作区处于活动状态时，如果用户的请求需要 Agent 调用工具来生成新内容（搜索、生成、分析等），第一步始终是 create-task——在此之前不要做任何其他事情。

决策流程：

1. 用户发送消息
2. 这条消息是否需要 Agent 调用工具来生成新内容？（搜索、生成、收集、分析、撰写）
   • 是 → 立即执行 create-task → 执行 → 执行 update-task 标记为已完成
   • 否 → 直接执行，无需创建任务

需要创建任务（调用工具来生成新内容）：

• “收集张先生的客户信息” → 需要搜索 + 生成
• “添加 10 个恐怖 TikTok 视频” → 需要搜索 + 添加内容
• “撰写竞争分析报告” → 需要生成
• “搜索近期金价走势” → 需要搜索

不需要创建任务（工作区操作）：

• “加载张先生的工作区” → 工作区操作
• “我的工作区里有什么？” → 查看工作区
• “刷新工作区” / “创建新工作区” → 工作区管理
• “保存那份报告” → 保存内容
• “更新 README” / “重命名工作区” → 工作区维护
• 闲聊、澄清问题

加载时： 拉取待处理和进行中的任务：

$SCRIPT tasks SHORT_ID --status 0
$SCRIPT tasks SHORT_ID --status 1

第一步——创建任务（在做任何其他事情之前）：

$SCRIPT create-task SHORT_ID --title "Task description" --status 1 --sort 0 [--operated-by "Agent Name"]

将返回的 task_id 保存到工作记忆中。

--title 应用一行概括用户想要完成的事项，例如：

• 用户说“收集张先生的信息” → --title "Collect client info on Mr. Zhang"
• 用户说“添加 10 个恐怖视频” → --title "Add 10 horror TikTok trending videos"

--operated-by 规则：

• 仅当 Agent 在本次会话中获得了名称时才传入（例如，分配了名称的 OpenClaw Agent）
• 如果没有明确名称，则省略（例如，普通的 Claude Code 会话）

最后一步——标记为已完成（执行后立即进行）：

$SCRIPT update-task SHORT_ID TASK_ID --status 2 [--operated-by "Agent Name"]

（--operated-by 规则同上——Agent 有名称时传入。）

静默执行——不要向用户叙述任务同步过程。如果开始前忘记创建任务，则事后补建，并立即标记为 DONE。绝不能跳过。

4. 保存内容（先询问）

生成重要内容后，询问用户：“要我将其保存到 [project] 工作区吗？”

重要内容 = 研究报告、竞争分析、会议摘要、生成的文档、关键数据导出。中间草稿无需保存。

类型	命令
文档	$SCRIPT add-doc SHORT_ID --title "Title" --content "content"
URL	$SCRIPT add-urls SHORT_ID --urls "URL"
文件	$SCRIPT upload SHORT_ID --file ./path --convert

保存后，回复：

“💾 已保存‘[Title]’📎 https://felo.ai/livedoc/SHORT_ID?from=claw”

5. README 维护

README 是 Agent 对项目的记忆，而不是工作日志。Agent 应主动维护，无需询问用户。

README 结构模板：

# [Project Name]

## What This Project Is
[Project background, objectives, stakeholders]

## User Preferences & Work Patterns
[How the user likes to work, what dimensions they care about, specific requirements]

## Current Progress
[Where things stand now — updated each session]
Last updated: YYYY-MM-DD

何时更新 README——核心问题：这次操作是否带来了新的理解？

更新（有新的理解）：

• 首次创建项目时——记录“这个项目是做什么的”
• 用户表达偏好或工作模式时——记录“用户希望如何开展工作”（例如，收集维度、关注领域、格式要求）
• 项目的性质或方向发生变化时

不更新（重复执行）：

• 重复进行相同模式的操作（例如，收集完张先生的信息后，再用相同模式收集李先生的信息——无需更新）
• 仅仅执行了某项操作（单凭生成一份文档不值得记录）

**更新方法：**读取 → 在内存中合并到正确的部分 → 完整写回。绝不要盲目追加到末尾。

1. $SCRIPT get-readme SHORT_ID 读取当前内容
2. 在内存中找到目标部分并插入：
   • 项目背景 → ## What This Project Is
   • 用户偏好 → ## User Preferences & Work Patterns
   • 进度变化 → 替换 ## Current Progress 部分内容
3. 将 Last updated: YYYY-MM-DD 更新为今天的日期
4. $SCRIPT update-readme SHORT_ID --content "..." 写回

初始化（README 为空或缺失）：跳过第 1 步，直接使用 update-readme 写入完整骨架。

更新后，告知用户：

"📝 README 已更新。📎 https://felo.ai/livedoc/SHORT_ID?from=claw"

6. 查询工作区

优先使用 resources + content（直接读取，免费），而不是 retrieve（基于大模型的语义搜索，需要付费）。

$SCRIPT resources SHORT_ID
$SCRIPT content SHORT_ID RESOURCE_ID
$SCRIPT retrieve SHORT_ID --query "question"   # fallback

将返回的内容综合成直接答案。不要原样倾倒原始结果。

7. 刷新工作区

当用户说“刷新”，或工作区可能已由外部更新（例如同事或另一会话更新），重新获取：

$SCRIPT get-readme SHORT_ID
$SCRIPT resources SHORT_ID
$SCRIPT tasks SHORT_ID --status 0
$SCRIPT tasks SHORT_ID --status 1

更新内存中的快照。告知用户：“工作区已刷新。”如果有任何变化，简要说明差异（新增资源、README 更新、新任务）。

8. 列出内容

$SCRIPT resources SHORT_ID，按类型分组，制品按时间倒序排列。

---

会话状态

ACTIVE_WORKSPACE = { name: "project-x", short_id: "abc123" }

• 用户加载或创建工作区时设置；用户说“关闭工作区”时清除
• 如果没有活动工作区，而用户尝试保存/记录/查询/创建任务：“没有活动工作区。请问是哪个项目？”

错误处理

错误	操作
缺少密钥 / 401 UNAUTHORIZED	触发登录流程（0a）
LiveDoc ID 已失效	提议重新关联或创建新的
注册表缺失	使用 {"workspaces": {}} 自动创建
模糊匹配结果不明确	列出所有匹配项，请用户选择

重要规则

• 所有内容都使用用户的语言——用户说中文就用中文，用户说英语就用英语
• 所有 LiveDoc 操作始终使用 short_id
• 立即执行命令——不要描述，直接行动
• 任务同步和 README 更新是 Agent 的职责——应主动执行，而不是被动响应
• 每次写入操作后都附上工作区链接